Introduce test whiteboard

This introduces a simple file-like attribute of every single test,
named, you guessed it right, `whiteboard`.

This can be written multiple times during the test run, or a single
time at the very end of the test, as the test writter wishes.

It will be automatically closed (and flushed) when the test ends.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado/test.py

@@ -29,6 +29,7 @@ from avocado.core import exceptions
 from avocado.utils import process
 from avocado.utils.params import Params
 from avocado import sysinfo
+from avocado import whiteboard
 
 log = logging.getLogger("avocado.test")
 
@@ -173,6 +174,9 @@ class Test(unittest.TestCase):
         self.traceback = None
         self.text_output = None
 
+        whiteboard_path = os.path.join(self.datadir, 'whiteboard')
+        self.whiteboard = whiteboard.WhiteBoard(self, whiteboard_path)
+
         self.time_elapsed = None
         unittest.TestCase.__init__(self)
 
@@ -314,6 +318,7 @@ class Test(unittest.TestCase):
             log_exc_info(sys.exc_info())
             action_exception = details
         finally:
+            self.whiteboard.close()
             try:
                 self.cleanup()
             except Exception, details:

avocado/whiteboard.py

+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See LICENSE for more details.
+#
+# Copyright: Red Hat Inc. 2013-2014
+# Authors: Cleber Rosa <cleber@redhat.com>
+
+
+class WhiteBoard(file):
+
+    '''
+    File-like, custom storage area for a running test.
+
+    It will be automatically persisted by the test framework right after the
+    test ends, whathever its outcome is.
+    '''
+
+    def __init__(self, test, name='whiteboard'):
+        '''
+        :param test: the test that owns this whiteboard instance.
+        :param name: the output file name
+        '''
+        super(WhiteBoard, self).__init__(name, 'w', 0)
+        self.test = test
+
+    def write(self, data, log=False):
+        '''
+        Write data into the whiteboard
+
+        Optionally, this can write the test data into the log so that data
+        which happens to be both human readable and machine useful can be
+        written at once.
+
+        :param data: any kind of test custom data
+        :param log: whether to log the written data using the test logger
+        '''
+        if log:
+            self.test.log.debug('Whiteboard data written: %s', data)
+        super(WhiteBoard, self).write(data)

docs/source/WritingTests.rst

@@ -51,6 +51,32 @@ we call a `multiplex file`, which is a configuration file that not only allows y
 to provide params to your test, but also easily create a validation matrix in a
 concise way. You can find more about the multiplex file format on :doc:`MultiplexConfig`.
 
+Saving test generated (custom) data
+===================================
+
+Each test instance provides a so called ``whiteboard``. It that can be accessed
+through ``self.whiteboard``. This whiteboard (see :class:`avocado.whiteboard.WhiteBoard`)
+is a simple file-like object that is ready for you to use.
+
+Building on the previously demonstrated sleeptest, supose that you want to save the
+sleep length to be used by some other script or data analysis tool::
+
+        def action(self):
+            """
+            Sleep for length seconds.
+            """
+            self.log.debug("Sleeping for %.2f seconds", self.params.sleep_length)
+            time.sleep(self.params.sleep_length)
+            self.whiteboard.write(self.params.sleep_length)
+
+The output path is always a file named ``whiteboard`` in the test instance
+``data directory``. This ``data directory`` itself is at the most obvious place,
+right along your ``debug.log`` file and ``sysinfo`` directory.
+
+The whiteboard file is always created, even if empty. This may sound like an inode
+waste, but can help debugging and asserts the whiteboard never had data written to.
+
+
 Accessing test parameters
 =========================