BeakerLib Newsletter #03: Journal

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 rlJournalStart command. rlJournalStart
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
from the TESTID environmental variable, used by Beaker to identify currently
running test instance. A user can also specify the desired directory directly
with the 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 BEAKERLIB_DIR),
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 raw or
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.

  • rlGetTestState returns the count of failed asserts in the whole test so far.
  • rlGetPhaseState returns the count of failed asserts in the currently opened phase (before rlPhaseEnd)

Next time: Logging text

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.