diff options
Diffstat (limited to 'logutils/testing.py')
-rw-r--r-- | logutils/testing.py | 64 |
1 files changed, 62 insertions, 2 deletions
diff --git a/logutils/testing.py b/logutils/testing.py index 1cb21e6..2a623ce 100644 --- a/logutils/testing.py +++ b/logutils/testing.py @@ -18,6 +18,13 @@ import logging from logging.handlers import BufferingHandler class TestHandler(BufferingHandler): + """ + This handler collects records in a buffer for later inspection by + your unit test code. + + :param matcher: The :class:`~logutils.testing.Matcher` instance to + use for matching. + """ def __init__(self, matcher): # BufferingHandler takes a "capacity" argument # so as to know when to flush. As we're overriding @@ -29,19 +36,41 @@ class TestHandler(BufferingHandler): self.matcher = matcher def shouldFlush(self): + """ + 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. + """ return False def emit(self, record): + """ + Saves the `__dict__` of the record in the `buffer` attribute, + and the formatted records in the `formatted` attribute. + + :param record: The record to emit. + """ self.formatted.append(self.format(record)) self.buffer.append(record.__dict__) def flush(self): + """ + Clears out the `buffer` and `formatted` attributes. + """ BufferingHandler.flush(self) self.formatted = [] def matches(self, **kwargs): """ Look for a saved dict whose keys/values match the supplied arguments. + + Return `True` if found, else `False`. + + :param kwargs: A set of keyword arguments whose names are LogRecord + attributes and whose values are what you want to + match in a stored LogRecord. """ result = False for d in self.buffer: @@ -56,6 +85,12 @@ class TestHandler(BufferingHandler): """ 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`. + + :param kwarglist: A list of keyword-argument dictionaries, each of + which will be passed to :meth:`matches` with the + corresponding record from the buffer. """ if self.count != len(kwarglist): result = False @@ -69,12 +104,25 @@ class TestHandler(BufferingHandler): @property def count(self): + """ + The number of records in the buffer. + """ return len(self.buffer) class Matcher(object): - + """ + This utility class matches a stored dictionary of + :class:`logging.LogRecord` attributes with keyword arguments + passed to its :meth:`~logutils.testing.Matcher.matches` method. + """ + _partial_matches = ('msg', 'message') - + """ + A list of :class:`logging.LogRecord` attribute names which + will be checked for partial matches. If not in this list, + an exact match will be attempted. + """ + def matches(self, d, **kwargs): """ Try to match a single dict with the supplied arguments. @@ -82,6 +130,12 @@ class Matcher(object): 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`. + + :param kwargs: A set of keyword arguments whose names are LogRecord + attributes and whose values are what you want to + match in a stored LogRecord. """ result = True for k in kwargs: @@ -96,6 +150,12 @@ class Matcher(object): def match_value(self, k, dv, v): """ Try to match a single stored value (dv) with a supplied value (v). + + Return `True` if found, else `False`. + + :param k: The key value (LogRecord attribute name). + :param dv: The stored value to match against. + :param v: The value to compare with the stored value. """ if type(v) != type(dv): result = False |