1 # Copyright (C) 2010 Chris Jerdonek (cjerdonek (at] webkit.org) 2 # 3 # Redistribution and use in source and binary forms, with or without 4 # modification, are permitted provided that the following conditions 5 # are met: 6 # 1. Redistributions of source code must retain the above copyright 7 # notice, this list of conditions and the following disclaimer. 8 # 2. Redistributions in binary form must reproduce the above copyright 9 # notice, this list of conditions and the following disclaimer in the 10 # documentation and/or other materials provided with the distribution. 11 # 12 # THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND 13 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 14 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 15 # DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR 16 # ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 18 # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 19 # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 20 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 21 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 22 23 """Supports the unit-testing of logging code. 24 25 Provides support for unit-testing messages logged using the built-in 26 logging module. 27 28 Inherit from the LoggingTestCase class for basic testing needs. For 29 more advanced needs (e.g. unit-testing methods that configure logging), 30 see the TestLogStream class, and perhaps also the LogTesting class. 31 32 """ 33 34 import logging 35 import unittest 36 37 38 class TestLogStream(object): 39 40 """Represents a file-like object for unit-testing logging. 41 42 This is meant for passing to the logging.StreamHandler constructor. 43 Log messages captured by instances of this object can be tested 44 using self.assertMessages() below. 45 46 """ 47 48 def __init__(self, test_case): 49 """Create an instance. 50 51 Args: 52 test_case: A unittest.TestCase instance. 53 54 """ 55 self._test_case = test_case 56 self.messages = [] 57 """A list of log messages written to the stream.""" 58 59 # Python documentation says that any object passed to the StreamHandler 60 # constructor should support write() and flush(): 61 # 62 # http://docs.python.org/library/logging.html#module-logging.handlers 63 def write(self, message): 64 self.messages.append(message) 65 66 def flush(self): 67 pass 68 69 def assertMessages(self, messages): 70 """Assert that the given messages match the logged messages. 71 72 messages: A list of log message strings. 73 74 """ 75 self._test_case.assertEquals(messages, self.messages) 76 77 78 class LogTesting(object): 79 80 """Supports end-to-end unit-testing of log messages. 81 82 Sample usage: 83 84 class SampleTest(unittest.TestCase): 85 86 def setUp(self): 87 self._log = LogTesting.setUp(self) # Turn logging on. 88 89 def tearDown(self): 90 self._log.tearDown() # Turn off and reset logging. 91 92 def test_logging_in_some_method(self): 93 call_some_method() # Contains calls to _log.info(), etc. 94 95 # Check the resulting log messages. 96 self._log.assertMessages(["INFO: expected message #1", 97 "WARNING: expected message #2"]) 98 99 """ 100 101 def __init__(self, test_stream, handler): 102 """Create an instance. 103 104 This method should never be called directly. Instances should 105 instead be created using the static setUp() method. 106 107 Args: 108 test_stream: A TestLogStream instance. 109 handler: The handler added to the logger. 110 111 """ 112 self._test_stream = test_stream 113 self._handler = handler 114 115 @staticmethod 116 def _getLogger(): 117 """Return the logger being tested.""" 118 # It is possible we might want to return something other than 119 # the root logger in some special situation. For now, the 120 # root logger seems to suffice. 121 return logging.getLogger() 122 123 @staticmethod 124 def setUp(test_case, logging_level=logging.INFO): 125 """Configure logging for unit testing. 126 127 Configures the root logger to log to a testing log stream. 128 Only messages logged at or above the given level are logged 129 to the stream. Messages logged to the stream are formatted 130 in the following way, for example-- 131 132 "INFO: This is a test log message." 133 134 This method should normally be called in the setUp() method 135 of a unittest.TestCase. See the docstring of this class 136 for more details. 137 138 Returns: 139 A LogTesting instance. 140 141 Args: 142 test_case: A unittest.TestCase instance. 143 logging_level: An integer logging level that is the minimum level 144 of log messages you would like to test. 145 146 """ 147 stream = TestLogStream(test_case) 148 handler = logging.StreamHandler(stream) 149 handler.setLevel(logging_level) 150 formatter = logging.Formatter("%(levelname)s: %(message)s") 151 handler.setFormatter(formatter) 152 153 # Notice that we only change the root logger by adding a handler 154 # to it. In particular, we do not reset its level using 155 # logger.setLevel(). This ensures that we have not interfered 156 # with how the code being tested may have configured the root 157 # logger. 158 logger = LogTesting._getLogger() 159 logger.addHandler(handler) 160 161 return LogTesting(stream, handler) 162 163 def tearDown(self): 164 """Assert there are no remaining log messages, and reset logging. 165 166 This method asserts that there are no more messages in the array of 167 log messages, and then restores logging to its original state. 168 This method should normally be called in the tearDown() method of a 169 unittest.TestCase. See the docstring of this class for more details. 170 171 """ 172 self.assertMessages([]) 173 logger = LogTesting._getLogger() 174 logger.removeHandler(self._handler) 175 176 def messages(self): 177 """Return the current list of log messages.""" 178 return self._test_stream.messages 179 180 # FIXME: Add a clearMessages() method for cases where the caller 181 # deliberately doesn't want to assert every message. 182 183 # We clear the log messages after asserting since they are no longer 184 # needed after asserting. This serves two purposes: (1) it simplifies 185 # the calling code when we want to check multiple logging calls in a 186 # single test method, and (2) it lets us check in the tearDown() method 187 # that there are no remaining log messages to be asserted. 188 # 189 # The latter ensures that no extra log messages are getting logged that 190 # the caller might not be aware of or may have forgotten to check for. 191 # This gets us a bit more mileage out of our tests without writing any 192 # additional code. 193 def assertMessages(self, messages): 194 """Assert the current array of log messages, and clear its contents. 195 196 Args: 197 messages: A list of log message strings. 198 199 """ 200 try: 201 self._test_stream.assertMessages(messages) 202 finally: 203 # We want to clear the array of messages even in the case of 204 # an Exception (e.g. an AssertionError). Otherwise, another 205 # AssertionError can occur in the tearDown() because the 206 # array might not have gotten emptied. 207 self._test_stream.messages = [] 208 209 210 # This class needs to inherit from unittest.TestCase. Otherwise, the 211 # setUp() and tearDown() methods will not get fired for test case classes 212 # that inherit from this class -- even if the class inherits from *both* 213 # unittest.TestCase and LoggingTestCase. 214 # 215 # FIXME: Rename this class to LoggingTestCaseBase to be sure that 216 # the unittest module does not interpret this class as a unittest 217 # test case itself. 218 class LoggingTestCase(unittest.TestCase): 219 220 """Supports end-to-end unit-testing of log messages. 221 222 Sample usage: 223 224 class SampleTest(LoggingTestCase): 225 226 def test_logging_in_some_method(self): 227 call_some_method() # Contains calls to _log.info(), etc. 228 229 # Check the resulting log messages. 230 self.assertLog(["INFO: expected message #1", 231 "WARNING: expected message #2"]) 232 233 """ 234 235 def setUp(self): 236 self._log = LogTesting.setUp(self) 237 238 def tearDown(self): 239 self._log.tearDown() 240 241 def logMessages(self): 242 """Return the current list of log messages.""" 243 return self._log.messages() 244 245 # FIXME: Add a clearMessages() method for cases where the caller 246 # deliberately doesn't want to assert every message. 247 248 # See the code comments preceding LogTesting.assertMessages() for 249 # an explanation of why we clear the array of messages after 250 # asserting its contents. 251 def assertLog(self, messages): 252 """Assert the current array of log messages, and clear its contents. 253 254 Args: 255 messages: A list of log message strings. 256 257 """ 258 self._log.assertMessages(messages) 259
