Unittesting Support
===================
.. currentmodule:: logbook
Logbook has builtin support for testing logging calls. There is a handler
that can be hooked in and will catch all log records for inspection. Not
only that, it also provides methods to test if certain things were logged.
Basic Setup
-----------
The interface to satisfaction is :class:`logbook.TestHandler`. Create it,
and bind it, and you're done. If you are using classic :mod:`unittest`
test cases, you might want to set it up in the before and after callback
methods::
import logbook
import unittest
class LoggingTestCase(unittest.TestCase):
def setUp(self):
self.log_handler = logbook.TestHandler()
self.log_handler.push_thread()
def tearDown(self):
self.log_handler.pop_thread()
Alternatively you can also use it in a with statement in an individual
test. This is also how this can work in nose and other testing systems::
def my_test():
with logbook.TestHandler() as log_handler:
...
Test Handler Interface
----------------------
The test handler has a few attributes and methods to gain access to the
logged messages. The most important ones are :attr:`~TestHandler.records`
and :attr:`~TestHandler.formatted_records`. The first is a list of the
captured :class:`~LogRecord`\s, the second a list of the formatted records
as unicode strings:
>>> from logbook import TestHandler, Logger
>>> logger = Logger('Testing')
>>> handler = TestHandler()
>>> handler.push_thread()
>>> logger.warn('Hello World')
>>> handler.records
[<logbook.base.LogRecord object at 0x100640cd0>]
>>> handler.formatted_records
[u'[WARNING] Testing: Hello World']
.. _probe-log-records:
Probe Log Records
-----------------
The handler also provide some convenience methods to do assertions:
>>> handler.has_warnings
True
>>> handler.has_errors
False
>>> handler.has_warning('Hello World')
True
Methods like :meth:`~logbook.TestHandler.has_warning` accept two
arguments:
`message`
If provided and not `None` it will check if there is at least one log
record where the message matches. This can also be a compiled regular
expression.
`channel`
If provided and not `None` it will check if there is at least one log
record where the logger name of the record matches.
Example usage:
>>> handler.has_warning('A different message')
False
>>> handler.has_warning(re.compile('^Hello'))
True
>>> handler.has_warning('Hello World', channel='Testing')
True
>>> handler.has_warning(channel='Testing')
True