/usr/share/doc/python-testfixtures-doc/html/logging.html is in python-testfixtures-doc 4.14.3-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 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 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 | <!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>Testing logging — testfixtures 4.14.3 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '4.14.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="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Testing output to streams" href="streams.html" />
<link rel="prev" title="Mocking dates and times" href="datetime.html" />
</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="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="streams.html" title="Testing output to streams"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="datetime.html" title="Mocking dates and times"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">testfixtures 4.14.3 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="testing-logging">
<h1>Testing logging<a class="headerlink" href="#testing-logging" title="Permalink to this headline">¶</a></h1>
<p>Python includes an excellent <a class="reference external" href="https://docs.python.org/3.5/library/logging.html#module-logging" title="(in Python v3.5)"><code class="xref py py-mod docutils literal"><span class="pre">logging</span></code></a> package, however many
people assume that logging calls do not need to be tested. They may
also want to test logging calls but find the prospect too daunting.
To help with this, TestFixtures allows you to easily capture the
output of calls to Python’s logging framework and make sure they were
as expected.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-class docutils literal"><span class="pre">LogCapture</span></code></a> class is useful for checking that
your code logs the right messages. If you want to check that
the configuration of your handlers is correct, please see
the <a class="reference internal" href="#check-log-config"><span class="std std-ref">section</span></a> below.</p>
</div>
<div class="section" id="methods-of-capture">
<h2>Methods of capture<a class="headerlink" href="#methods-of-capture" title="Permalink to this headline">¶</a></h2>
<p>There are three different techniques for capturing messages logged to
the Python logging framework, depending on the type of test you are
writing. They are all described in the sections below.</p>
<div class="section" id="the-context-manager">
<h3>The context manager<a class="headerlink" href="#the-context-manager" title="Permalink to this headline">¶</a></h3>
<p>If you’re using a version of Python where the <code class="docutils literal"><span class="pre">with</span></code> keyword is
available, the context manager provided by TestFixtures can be used:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">logging</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">testfixtures</span> <span class="k">import</span> <span class="n">LogCapture</span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">LogCapture</span><span class="p">()</span> <span class="k">as</span> <span class="n">l</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'a message'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'an error'</span><span class="p">)</span>
</pre></div>
</div>
<p>For the duration of the <code class="docutils literal"><span class="pre">with</span></code> block, log messages are captured. The
context manager provides a check method that raises an exception if
the logging wasn’t as you expected:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">(</span>
<span class="gp">... </span> <span class="p">(</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'a message'</span><span class="p">),</span>
<span class="gp">... </span> <span class="p">(</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'ERROR'</span><span class="p">,</span> <span class="s1">'another error'</span><span class="p">),</span>
<span class="gp">... </span> <span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AssertionError</span>: <span class="n">sequence not as expected:</span>
<span class="go">same:</span>
<span class="go">(('root', 'INFO', 'a message'),)</span>
<span class="go">expected:</span>
<span class="go">(('root', 'ERROR', 'another error'),)</span>
<span class="go">actual:</span>
<span class="go">(('root', 'ERROR', 'an error'),)</span>
</pre></div>
</div>
<p>It also has a string representation that allows you to see what has
been logged, which is useful for doc tests:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">root INFO</span>
<span class="go"> a message</span>
<span class="go">root ERROR</span>
<span class="go"> an error</span>
</pre></div>
</div>
</div>
<div class="section" id="the-decorator">
<h3>The decorator<a class="headerlink" href="#the-decorator" title="Permalink to this headline">¶</a></h3>
<p>If you are working in a traditional <a class="reference external" href="https://docs.python.org/3.5/library/unittest.html#module-unittest" title="(in Python v3.5)"><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> environment and
only want to capture logging for a particular test function, you may
find the decorator suits your needs better:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">testfixtures</span> <span class="kn">import</span> <span class="n">log_capture</span>
<span class="nd">@log_capture</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">l</span><span class="p">):</span>
<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>
<span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'a message'</span><span class="p">)</span>
<span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'an error'</span><span class="p">)</span>
<span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">(</span>
<span class="p">(</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'a message'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'ERROR'</span><span class="p">,</span> <span class="s1">'an error'</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="manual-usage">
<h3>Manual usage<a class="headerlink" href="#manual-usage" title="Permalink to this headline">¶</a></h3>
<p>If you want to capture logging for the duration of a doctest or
in every test in a <a class="reference external" href="https://docs.python.org/3.5/library/unittest.html#unittest.TestCase" title="(in Python v3.5)"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>, then you can use the
<a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-class docutils literal"><span class="pre">LogCapture</span></code></a> manually.</p>
<p>The instantiation and replacement are done in the <code class="docutils literal"><span class="pre">setUp</span></code> function
of the <a class="reference external" href="https://docs.python.org/3.5/library/unittest.html#unittest.TestCase" title="(in Python v3.5)"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> or passed to the
<code class="xref py py-class docutils literal"><span class="pre">DocTestSuite</span></code> constructor:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">testfixtures</span> <span class="k">import</span> <span class="n">LogCapture</span>
<span class="gp">>>> </span><span class="n">l</span> <span class="o">=</span> <span class="n">LogCapture</span><span class="p">()</span>
</pre></div>
</div>
<p>You can then execute whatever will log the messages you want to test
for:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">logging</span> <span class="k">import</span> <span class="n">getLogger</span>
<span class="gp">>>> </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">'a message'</span><span class="p">)</span>
</pre></div>
</div>
<p>At any point, you can check what has been logged using the
check method:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">((</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'a message'</span><span class="p">))</span>
</pre></div>
</div>
<p>Alternatively, you can use the string representation of the
<a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-class docutils literal"><span class="pre">LogCapture</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">root INFO</span>
<span class="go"> a message</span>
</pre></div>
</div>
<p>Then, in the <code class="docutils literal"><span class="pre">tearDown</span></code> function
of the <a class="reference external" href="https://docs.python.org/3.5/library/unittest.html#unittest.TestCase" title="(in Python v3.5)"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> or passed to the
<code class="xref py py-class docutils literal"><span class="pre">DocTestSuite</span></code> constructor, you should make sure you
stop the capturing:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">uninstall</span><span class="p">()</span>
</pre></div>
</div>
<p>If you have multiple <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-class docutils literal"><span class="pre">LogCapture</span></code></a> objects in use,
you can easily uninstall them all:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">LogCapture</span><span class="o">.</span><span class="n">uninstall_all</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="checking-captured-log-messages">
<h2>Checking captured log messages<a class="headerlink" href="#checking-captured-log-messages" title="Permalink to this headline">¶</a></h2>
<p>Regardless of how you use the <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-class docutils literal"><span class="pre">LogCapture</span></code></a> to
capture messages, there are three ways of checking that the messages
captured were as expected.</p>
<p>The following example is useful for showing these:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">testfixtures</span> <span class="kn">import</span> <span class="n">LogCapture</span>
<span class="kn">from</span> <span class="nn">logging</span> <span class="kn">import</span> <span class="n">getLogger</span>
<span class="n">logger</span> <span class="o">=</span> <span class="n">getLogger</span><span class="p">()</span>
<span class="k">with</span> <span class="n">LogCapture</span><span class="p">()</span> <span class="k">as</span> <span class="n">l</span><span class="p">:</span>
<span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'start of block number </span><span class="si">%i</span><span class="s1">'</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s1">'No code to run!'</span><span class="p">)</span>
<span class="k">except</span><span class="p">:</span>
<span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'error occurred'</span><span class="p">,</span> <span class="n">exc_info</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="the-check-method">
<h3>The check method<a class="headerlink" href="#the-check-method" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-obj docutils literal"><span class="pre">LogCapture</span></code></a> has a
<a class="reference internal" href="api.html#testfixtures.LogCapture.check" title="testfixtures.LogCapture.check"><code class="xref py py-meth docutils literal"><span class="pre">check()</span></code></a> method that will compare the
log messages captured with those you expect. Expected messages are
expressed as three-element tuples where the first element is the name
of the logger to which the message should have been logged, the
second element is the string representation of the level at which the
message should have been logged and the third element is the message
that should have been logged after any parameter interpolation has
taken place.</p>
<p>If things are as you expected, the method will not raise any exceptions:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">(</span>
<span class="gp">... </span> <span class="p">(</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'start of block number 1'</span><span class="p">),</span>
<span class="gp">... </span> <span class="p">(</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'ERROR'</span><span class="p">,</span> <span class="s1">'error occurred'</span><span class="p">),</span>
<span class="gp">... </span> <span class="p">)</span>
</pre></div>
</div>
<p>However, if the actual messages logged were different, you’ll get an
<code class="xref py py-class docutils literal"><span class="pre">AssertionError</span></code> explaining what happened:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">((</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'start of block number 1'</span><span class="p">))</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AssertionError</span>: <span class="n">sequence not as expected:</span>
<span class="go">same:</span>
<span class="go">(('root', 'INFO', 'start of block number 1'),)</span>
<span class="go">expected:</span>
<span class="go">()</span>
<span class="go">actual:</span>
<span class="go">(('root', 'ERROR', 'error occurred'),)</span>
</pre></div>
</div>
</div>
<div class="section" id="printing">
<h3>Printing<a class="headerlink" href="#printing" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-obj docutils literal"><span class="pre">LogCapture</span></code></a> has a string representation that
shows what messages it has captured. This can be useful in doc tests:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">root INFO</span>
<span class="go"> start of block number 1</span>
<span class="go">root ERROR</span>
<span class="go"> error occurred</span>
</pre></div>
</div>
<p>This representation can also be used to check that no logging has
occurred:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">empty</span> <span class="o">=</span> <span class="n">LogCapture</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">empty</span><span class="p">)</span>
<span class="go">No logging captured</span>
</pre></div>
</div>
</div>
<div class="section" id="inspecting">
<h3>Inspecting<a class="headerlink" href="#inspecting" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-obj docutils literal"><span class="pre">LogCapture</span></code></a> also keeps a list of the
<a class="reference external" href="https://docs.python.org/3.5/library/logging.html#logging.LogRecord" title="(in Python v3.5)"><code class="xref py py-class docutils literal"><span class="pre">LogRecord</span></code></a> instances it captures. This is useful when
you want to check specifics of the captured logging that aren’t
available from either the string representation or the
<a class="reference internal" href="api.html#testfixtures.LogCapture.check" title="testfixtures.LogCapture.check"><code class="xref py py-meth docutils literal"><span class="pre">check()</span></code></a> method.</p>
<p>A common case of this is where you want to check that exception
information was logged for certain messages:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="o">.</span><span class="n">records</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">exc_info</span><span class="p">)</span>
<span class="go">(<... '...RuntimeError'>, RuntimeError('No code to run!',), <traceback object at ...>)</span>
</pre></div>
</div>
<p>If you’re working in a unit test, the following code may be more
appropriate:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">testfixtures</span> <span class="kn">import</span> <span class="n">compare</span><span class="p">,</span> <span class="n">Comparison</span> <span class="k">as</span> <span class="n">C</span>
<span class="n">compare</span><span class="p">(</span><span class="n">C</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">(</span><span class="s1">'No code to run!'</span><span class="p">)),</span> <span class="n">l</span><span class="o">.</span><span class="n">records</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">exc_info</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="only-capturing-specific-logging">
<h2>Only capturing specific logging<a class="headerlink" href="#only-capturing-specific-logging" title="Permalink to this headline">¶</a></h2>
<p>Some actions that you want to test may generate a lot of logging, only
some of which you actually need to care about.</p>
<p>The logging you care about is often only that above a certain log
level. If this is the case, you can configure <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-obj docutils literal"><span class="pre">LogCapture</span></code></a> to
only capture logging at or above a specific level.</p>
<p>If using the context manager, you would do this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="n">LogCapture</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span> <span class="k">as</span> <span class="n">l</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">logger</span> <span class="o">=</span> <span class="n">getLogger</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">'junk'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'something we care about'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'an error'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">root INFO</span>
<span class="go"> something we care about</span>
<span class="go">root ERROR</span>
<span class="go"> an error</span>
</pre></div>
</div>
<p>If using the decorator, you would do this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="nd">@log_capture</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">l</span><span class="p">):</span>
<span class="n">logger</span><span class="o">=</span> <span class="n">getLogger</span><span class="p">()</span>
<span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">'junk'</span><span class="p">)</span>
<span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'what we care about'</span><span class="p">)</span>
<span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">((</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'what we care about'</span><span class="p">))</span>
</pre></div>
</div>
<p>In other cases this problem can be alleviated by only capturing a
specific logger.</p>
<p>If using the context manager, you would do this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="n">LogCapture</span><span class="p">(</span><span class="s1">'specific'</span><span class="p">)</span> <span class="k">as</span> <span class="n">l</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">getLogger</span><span class="p">(</span><span class="s1">'something'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'junk'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">getLogger</span><span class="p">(</span><span class="s1">'specific'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'what we care about'</span><span class="p">)</span>
<span class="gp">... </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">'more junk'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">specific INFO</span>
<span class="go"> what we care about</span>
</pre></div>
</div>
<p>If using the decorator, you would do this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="nd">@log_capture</span><span class="p">(</span><span class="s1">'specific'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">l</span><span class="p">):</span>
<span class="n">getLogger</span><span class="p">(</span><span class="s1">'something'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'junk'</span><span class="p">)</span>
<span class="n">getLogger</span><span class="p">(</span><span class="s1">'specific'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'what we care about'</span><span class="p">)</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">'more junk'</span><span class="p">)</span>
<span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">((</span><span class="s1">'specific'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'what we care about'</span><span class="p">))</span>
</pre></div>
</div>
<p>However, it may be that while you don’t want to capture all logging,
you do want to capture logging from multiple specific loggers.</p>
<p>You would do this with the context manager as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="n">LogCapture</span><span class="p">((</span><span class="s1">'one'</span><span class="p">,</span><span class="s1">'two'</span><span class="p">))</span> <span class="k">as</span> <span class="n">l</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">getLogger</span><span class="p">(</span><span class="s1">'three'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'3'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">getLogger</span><span class="p">(</span><span class="s1">'two'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'2'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">getLogger</span><span class="p">(</span><span class="s1">'one'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'1'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">two INFO</span>
<span class="go"> 2</span>
<span class="go">one INFO</span>
<span class="go"> 1</span>
</pre></div>
</div>
<p>Likewise, the same thing can be done with the decorator:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="nd">@log_capture</span><span class="p">(</span><span class="s1">'one'</span><span class="p">,</span><span class="s1">'two'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">l</span><span class="p">):</span>
<span class="n">getLogger</span><span class="p">(</span><span class="s1">'three'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'3'</span><span class="p">)</span>
<span class="n">getLogger</span><span class="p">(</span><span class="s1">'two'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'2'</span><span class="p">)</span>
<span class="n">getLogger</span><span class="p">(</span><span class="s1">'one'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'1'</span><span class="p">)</span>
<span class="n">l</span><span class="o">.</span><span class="n">check</span><span class="p">(</span>
<span class="p">(</span><span class="s1">'two'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'2'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'one'</span><span class="p">,</span> <span class="s1">'INFO'</span><span class="p">,</span> <span class="s1">'1'</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>
</div>
<p>It may also be that the simplest thing to do is only capture logging
for part of your test. This is particularly common with long doc
tests. To make this easier, <a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-obj docutils literal"><span class="pre">LogCapture</span></code></a> supports
manual installation and uninstallation as shown in the following
example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">l</span> <span class="o">=</span> <span class="n">LogCapture</span><span class="p">(</span><span class="n">install</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">>>> </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">'junk'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">install</span><span class="p">()</span>
<span class="gp">>>> </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">'something we care about'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">uninstall</span><span class="p">()</span>
<span class="gp">>>> </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">'more junk'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">l</span><span class="o">.</span><span class="n">install</span><span class="p">()</span>
<span class="gp">>>> </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">'something else we care about'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
<span class="go">root INFO</span>
<span class="go"> something we care about</span>
<span class="go">root INFO</span>
<span class="go"> something else we care about</span>
</pre></div>
</div>
</div>
<div class="section" id="checking-the-configuration-of-your-log-handlers">
<span id="check-log-config"></span><h2>Checking the configuration of your log handlers<a class="headerlink" href="#checking-the-configuration-of-your-log-handlers" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="api.html#testfixtures.LogCapture" title="testfixtures.LogCapture"><code class="xref py py-class docutils literal"><span class="pre">LogCapture</span></code></a> is good for checking that your code is logging the
correct messages; just as important is checking that your application
has correctly configured log handers. This can be done using a unit
test such as the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">testfixtures</span> <span class="kn">import</span> <span class="n">Comparison</span> <span class="k">as</span> <span class="n">C</span><span class="p">,</span> <span class="n">compare</span>
<span class="kn">from</span> <span class="nn">unittest</span> <span class="kn">import</span> <span class="n">TestCase</span>
<span class="kn">import</span> <span class="nn">logging</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="k">class</span> <span class="nc">LoggingConfigurationTests</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
<span class="c1"># We mock out the handlers list for the logger we're</span>
<span class="c1"># configuring in such a way that we have no handlers</span>
<span class="c1"># configured at the start of the test and the handlers our</span>
<span class="c1"># configuration installs are removed at the end of the test.</span>
<span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">orig_handlers</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">handlers</span>
<span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">handlers</span> <span class="o">=</span> <span class="p">[]</span>
<span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">level</span>
<span class="k">def</span> <span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">handlers</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">orig_handlers</span>
<span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">level</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">level</span>
<span class="k">def</span> <span class="nf">test_basic_configuration</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># Our logging configuration code, in this case just a</span>
<span class="c1"># call to basicConfig:</span>
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">format</span><span class="o">=</span><span class="s1">'</span><span class="si">%(levelname)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span><span class="p">,</span>
<span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
<span class="c1"># Now we check the configuration is as expected:</span>
<span class="n">compare</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">level</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
<span class="n">compare</span><span class="p">([</span>
<span class="n">C</span><span class="p">(</span><span class="s1">'logging.StreamHandler'</span><span class="p">,</span>
<span class="n">stream</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">,</span>
<span class="n">formatter</span><span class="o">=</span><span class="n">C</span><span class="p">(</span><span class="s1">'logging.Formatter'</span><span class="p">,</span>
<span class="n">_fmt</span><span class="o">=</span><span class="s1">'</span><span class="si">%(levelname)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span><span class="p">,</span>
<span class="n">strict</span><span class="o">=</span><span class="bp">False</span><span class="p">),</span>
<span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">NOTSET</span><span class="p">,</span>
<span class="n">strict</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="p">],</span> <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">handlers</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">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Testing logging</a><ul>
<li><a class="reference internal" href="#methods-of-capture">Methods of capture</a><ul>
<li><a class="reference internal" href="#the-context-manager">The context manager</a></li>
<li><a class="reference internal" href="#the-decorator">The decorator</a></li>
<li><a class="reference internal" href="#manual-usage">Manual usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#checking-captured-log-messages">Checking captured log messages</a><ul>
<li><a class="reference internal" href="#the-check-method">The check method</a></li>
<li><a class="reference internal" href="#printing">Printing</a></li>
<li><a class="reference internal" href="#inspecting">Inspecting</a></li>
</ul>
</li>
<li><a class="reference internal" href="#only-capturing-specific-logging">Only capturing specific logging</a></li>
<li><a class="reference internal" href="#checking-the-configuration-of-your-log-handlers">Checking the configuration of your log handlers</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="datetime.html"
title="previous chapter">Mocking dates and times</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="streams.html"
title="next chapter">Testing output to streams</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/logging.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<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="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="streams.html" title="Testing output to streams"
>next</a> |</li>
<li class="right" >
<a href="datetime.html" title="Mocking dates and times"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">testfixtures 4.14.3 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2008-2017 Simplistix Ltd, 2016-2017 Chris Withers.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
</div>
</body>
</html>
|