Unit testing

When developing unit tests, you may find the TestHandler and Matcher classes useful.

Typical usage:

import logging
from logutils.testing import TestHandler, Matcher
import unittest

class LoggingTest(unittest.TestCase):
    def setUp(self):
        self.handler = h = TestHandler(Matcher())
        self.logger = l = logging.getLogger()
        l.addHandler(h)

    def tearDown(self):
        self.logger.removeHandler(self.handler)
        self.handler.close()

    def test_simple(self):
        "Simple test of logging test harness."
        # Just as a demo, let's log some messages.
        # Only one should show up in the log.
        self.logger.debug("This won't show up.")
        self.logger.info("Neither will this.")
        self.logger.warning("But this will.")
        h = self.handler
        self.assertTrue(h.matches(levelno=logging.WARNING))
        self.assertFalse(h.matches(levelno=logging.DEBUG))
        self.assertFalse(h.matches(levelno=logging.INFO))

    def test_partial(self):
        "Test of partial matching in logging test harness."
        # Just as a demo, let's log some messages.
        # Only one should show up in the log.
        self.logger.debug("This won't show up.")
        self.logger.info("Neither will this.")
        self.logger.warning("But this will.")
        h = self.handler
        self.assertTrue(h.matches(msg="ut th")) # from "But this will"
        self.assertTrue(h.matches(message="ut th")) # from "But this will"
        self.assertFalse(h.matches(message="either"))
        self.assertFalse(h.matches(message="won't"))

    def test_multiple(self):
        "Test of matching multiple values in logging test harness."
        # Just as a demo, let's log some messages.
        # Only one should show up in the log.
        self.logger.debug("This won't show up.")
        self.logger.info("Neither will this.")
        self.logger.warning("But this will.")
        self.logger.error("And so will this.")
        h = self.handler
        self.assertTrue(h.matches(levelno=logging.WARNING,
                                  message='ut thi'))
        self.assertTrue(h.matches(levelno=logging.ERROR,
                                  message='nd so wi'))
        self.assertFalse(h.matches(levelno=logging.INFO))

class logutils.testing.Matcher

This utility class matches a stored dictionary of logging.LogRecord attributes with keyword arguments passed to its matches() method.

match_value(k, dv, v)

Try to match a single stored value (dv) with a supplied value (v).

Return True if found, else False.

Parameters:

• k – The key value (LogRecord attribute name).
• dv – The stored value to match against.
• v – The value to compare with the stored value.

matches(d, **kwargs)

Try to match a single dict with the supplied arguments.

Keys whose values are strings and which are in self._partial_matches will be checked for partial (i.e. substring) matches. You can extend this scheme to (for example) do regular expression matching, etc.

Return True if found, else False.

Parameters:kwargs – A set of keyword arguments whose names are LogRecord attributes and whose values are what you want to match in a stored LogRecord.

class logutils.testing.TestHandler(matcher)

This handler collects records in a buffer for later inspection by your unit test code.

Parameters:matcher – The Matcher instance to use for matching.

count

The number of records in the buffer.

emit(record)

Saves the __dict__ of the record in the buffer attribute, and the formatted records in the formatted attribute.

Parameters:record – The record to emit.

flush()

Clears out the buffer and formatted attributes.

matchall(kwarglist)

Accept a list of keyword argument values and ensure that the handler’s buffer of stored records matches the list one-for-one.

Return True if exactly matched, else False.

Parameters:kwarglist – A list of keyword-argument dictionaries, each of which will be passed to matches() with the corresponding record from the buffer.

matches(**kwargs)

Look for a saved dict whose keys/values match the supplied arguments.

Return True if found, else False.

Parameters:kwargs – A set of keyword arguments whose names are LogRecord attributes and whose values are what you want to match in a stored LogRecord.

shouldFlush()

Should the buffer be flushed?

This returns False - you’ll need to flush manually, usually after your unit test code checks the buffer contents against your expectations.