The Journal is a core piece of BeakerLib. It is an on-disk log of a test
progress: whenever you do a rl-Something, an information about the command
execution and result is stored in it. It is simply an XML-formatted document.
It is used to generate a human-readable test protocol, and it is also uploaded
to Beaker in its raw form to allow automated processing. These artifacts are
generated and uploaded whenever a Phase is finished, so we have partial results
available after each Phase.
Starting the Journal
A Journal is initialized with the
collects information about the test environment and sets up the necessary
files. All necessary files are stored in a single directory. This directory is
either randomly selected (when running outside of Beaker), or it is inferred
TESTID environmental variable, used by Beaker to identify currently
running test instance. A user can also specify the desired directory directly
BEAKERLIB_DIR environmental variable.
It is important to note that if an already opened journal is found in the
directory at the time of running
rlJournalStart, it is neither deleted nor
reset to be empty. In this case, it is assumed that the we continue a test run
started earlier. So, if reusing a directory (e.g. when using
the user is responsible for cleaning it before the test is run.
Finishing the journal
From the Journal perspective, there is nothing like a finished Journal: at all
times, the Journal is a full and valid log of what happened and new records may
always be added to it. Because results are processed at the end of the Phases,
there is nothing much to do at the end of the test. Still, because there may
be some future features wanting to do something at the end of the test, the
test execution should be concluded with the
rlJournalEnd command. Currently,
this command generates the full test protocol and final XML, and uploads them
to Beaker. Automated cleanup will also happen at this point when this feature
is finished. After running
rlJournalEnd, there should be no other commands
executed in the test, neither BeakerLib ones, nor any other.
Printing the Journal
Sometimes it is useful to print the current journal content. While this is not very useful in tests, it might be handy when running a test manually or during debugging.
Printing human readable protocol
rlJournalPrintText prints a pretty test protocol in plain text. With an
--full-journal option, it prints additional records, like detailed HW
information. The simple version should be sufficient most of the time.
Printing the XML
rlJournalPrint dumps the full XML document. It accepts either
pretty as argument, with the latter being the default. Raw version is better
machine readable, as there is no additional prettifying mess (indentation,
linebreaks, etc.). Pretty version looks pretty to humans: there is a single
element per line, everything is indented, but the information is lost about
what was added when prettifying and what was in the original file.
Querying the state so far
The journal can give a test an information about the current state of
execution, at both phase and test level. Therefore, the test can choose to e.g.
not run some part of itself when a critical setup failed.
rlGetTestStatereturns the count of failed asserts in the whole test so far.
rlGetPhaseStatereturns the count of failed asserts in the currently opened phase (before
Next time: Logging text