Add AutoTimingTestResultDecorator.

4 files changed, 102 insertions, 7 deletions

diff --git a/NEWS b/NEWS
index 1c7fe1b..ef74b43 100644
--- a/NEWS
+++ b/NEWS
@@ -19,11 +19,15 @@ subunit release notes
 
   INTERNALS:
 
-    * ExecTestCase supports passing arguments to test scripts.
+    * (python) Added ``subunit.test_results.AutoTimingTestResultDecorator``. Most
+      users of subunit will want to wrap their ``TestProtocolClient`` objects
+      in this decorator to get test timing data for performance analysis.
 
-    * New helper ``subunit.test_results.HookedTestResultDecorator`` which can
-      be used to call some code on every event, without having to implement all
-      the event methods.
+    * (python) ExecTestCase supports passing arguments to test scripts.
 
-    * ``TestProtocolClient.time(a_datetime)`` has been added which causes a
-      timestamp to be output to the stream.
+    * (python) New helper ``subunit.test_results.HookedTestResultDecorator``
+      which can be used to call some code on every event, without having to
+      implement all the event methods.
+
+    * (python) ``TestProtocolClient.time(a_datetime)`` has been added which
+      causes a timestamp to be output to the stream.
diff --git a/README b/README
index 786a965..d64d8f9 100644
--- a/README
+++ b/README
@@ -72,6 +72,9 @@ Subunit stream::
  stream = file('tests.log', 'wb')
  # Create a subunit result object which will output to the stream
  result = subunit.TestProtocolClient(stream)
+ # Optionally, to get timing data for performance analysis, wrap the
+ # serialiser with a timing decorator
+ result = subunit.test_results.AutoTimingTestResultDecorator(result)
  # Run the test suite reporting to the subunit result object
  suite.run(result)
  # Close the stream.
diff --git a/python/subunit/test_results.py b/python/subunit/test_results.py
index aab86b0..4ba9169 100644
--- a/python/subunit/test_results.py
+++ b/python/subunit/test_results.py
@@ -19,6 +19,9 @@
 
 """TestResult helper classes used to by subunit."""
 
+import datetime
+
+import iso8601
 
 class HookedTestResultDecorator(object):
     """A TestResult which calls a hook on every event."""
@@ -91,3 +94,38 @@ class HookedTestResultDecorator(object):
     def stop(self):
         self._before_event()
         return self.decorated.stop()
+
+    def time(self, a_datetime):
+        self._before_event()
+        return self._call_maybe("time", a_datetime)
+
+
+class AutoTimingTestResultDecorator(HookedTestResultDecorator):
+    """Decorate a TestResult to add time events to a test run.
+
+    By default this will cause a time event before every test event,
+    but if explicit time data is being provided by the test run, then
+    this decorator will turn itself off to prevent causing confusion.
+    """
+
+    def __init__(self, decorated):
+        self._time = None
+        super(AutoTimingTestResultDecorator, self).__init__(decorated)
+
+    def _before_event(self):
+        time = self._time
+        if time is not None:
+            return
+        time = datetime.datetime.utcnow().replace(tzinfo=iso8601.Utc())
+        self._call_maybe("time", time)
+
+    def time(self, a_datetime):
+        """Provide a timestamp for the current test activity.
+
+        :param a_datetime: If None, automatically add timestamps before every
+            event (this is the default behaviour if time() is not called at
+            all).  If not None, pass the provided time onto the decorated
+            result object and disable automatic timestamps.
+        """
+        self._time = a_datetime
+        return self._call_maybe("time", a_datetime)
diff --git a/python/subunit/tests/test_test_results.py b/python/subunit/tests/test_test_results.py
index a020ba2..65b9452 100644
--- a/python/subunit/tests/test_test_results.py
+++ b/python/subunit/tests/test_test_results.py
@@ -49,6 +49,15 @@ class AssertBeforeTestResult(LoggingDecorator):
         super(AssertBeforeTestResult, self)._before_event()
 
 
+class TimeCapturingResult(unittest.TestResult):
+
+    def __init__(self):
+        super(TimeCapturingResult, self).__init__()
+        self._calls = []
+
+    def time(self, a_datetime):
+        self._calls.append(a_datetime)
+
 
 class TestHookedTestResultDecorator(unittest.TestCase):
 
@@ -104,7 +113,48 @@ class TestHookedTestResultDecorator(unittest.TestCase):
 
     def test_stop(self):
         self.result.stop()
-        
+
+    def test_time(self):
+        self.result.time(None)
+ 
+
+class TestAutoTimingTestResultDecorator(unittest.TestCase):
+
+    def setUp(self):
+        # And end to the chain which captures time events.
+        terminal = TimeCapturingResult()
+        # The result object under test.
+        self.result = subunit.test_results.AutoTimingTestResultDecorator(
+            terminal)
+
+    def test_without_time_calls_time_is_called_and_not_None(self):
+        self.result.startTest(self)
+        self.assertEqual(1, len(self.result.decorated._calls))
+        self.assertNotEqual(None, self.result.decorated._calls[0])
+
+    def test_calling_time_inhibits_automatic_time(self):
+        # Calling time() outputs a time signal immediately and prevents
+        # automatically adding one when other methods are called.
+        time = datetime.datetime(2009,10,11,12,13,14,15, iso8601.Utc())
+        self.result.time(time)
+        self.result.startTest(self)
+        self.result.stopTest(self)
+        self.assertEqual(1, len(self.result.decorated._calls))
+        self.assertEqual(time, self.result.decorated._calls[0])
+
+    def test_calling_time_None_enables_automatic_time(self):
+        time = datetime.datetime(2009,10,11,12,13,14,15, iso8601.Utc())
+        self.result.time(time)
+        self.assertEqual(1, len(self.result.decorated._calls))
+        self.assertEqual(time, self.result.decorated._calls[0])
+        # Calling None passes the None through, in case other results care.
+        self.result.time(None)
+        self.assertEqual(2, len(self.result.decorated._calls))
+        self.assertEqual(None, self.result.decorated._calls[1])
+        # Calling other methods doesn't generate an automatic time event.
+        self.result.startTest(self)
+        self.assertEqual(3, len(self.result.decorated._calls))
+        self.assertNotEqual(None, self.result.decorated._calls[2])
 
 
 def test_suite():