### Navigation

- index
- modules |
- next |
- previous |
- Logutils 0.3.3 documentation »

# 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.

### Navigation

- index
- modules |
- next |
- previous |
- Logutils 0.3.3 documentation »