.. include:: ../../../doc/userguide/src/roles.rst

================
statuschecker.py
================

:prog:`statuschecker.py` is a tool for checking that Robot Framework
test cases have expected statuses and log messages.  It is included in
source distributions and can also be downloaded from
http://code.google.com/p/robotframework/wiki/TestStatusCheckerTool.


Synopsis
--------

::

    statuschecker.py infile [outfile]


Description
-----------

This tool processes Robot Framework output XML files and checks that
test case statuses and messages are as expected. The main use case is
post-processing output files got when testing Robot Framework test
libraries using Robot Framework itself.

If an output file is not given, the input file is considered to be
also an output file and it is edited in place.


Defining expected test status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, all test cases are expected to :msg:`PASS` and have no
message. Changing the expected status to :msg:`FAIL` is done by having
the word :msg:`FAIL` (in uppercase) somewhere in the test case
documentation. The expected error message must then be given after
:msg:`FAIL`.

The error message can also be specified as a regular expression by
prefixing it with :msg:`REGEXP:`. The specified regular expression
must match the error message fully. Having spaces between the status,
the message or the possible regular expression prefix is optional.

It is also possible to test only the beginning of the error by
prefixing the expected message with :msg:`STARTS:`.

.. table:: Examples
   :class: example

   =================  ===============  =========  =============================
       Test Case           Action      Arguments           Arguments
   =================  ===============  =========  =============================
   Simple Example     [Documentation]  FAIL       Expected error message
   \                  Steps            \          \
   Regexp Example     [Documentation]  FAIL       REGEXP: (IOError|OSError): .*
   \                  Steps            \          \
   Start Example      [Documentation]  FAIL       STARTS: IOError:
   \                  Steps            \          \
   =================  ===============  =========  =============================


Defining expected log messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The expected keyword log messages can also be defined in the test case
documentation using a syntax such as::

   LOG x.y:z LEVEL Actual message

The part before the colon is the number of the keyword to check. For
example :msg:`1` means first keyword, :msg:`1.2` is the second child
keyword of the first keyword, and so on.

The part after the colon denotes the number of the message. For
example :msg:`1:2` means the second message of the first keyword and
:msg:`1.2:3` is the third message of the second child keyword of the
first keyword. The message index is optional and defaults to :msg:`1`.

Message level is specified before the actual message, and it can be
any of the valid log levels in capital letters. If the level is not
given it defaults to :msg:`INFO`.

This syntax can be used multiple times to test multiple messages.  It
also workstogether with specifying the expected error message with
:msg:`FAIL`, but it that case :msg:`FAIL` and the expected error must
be first.

The log message can also be given as a regular expression pattern the
same way as the `expected error message`__. Finally, to check that a
keyword does not have a certain message, it is possible to use
:msg:`NONE` in the place of the message.

__ `Defining expected test status`_


.. table:: Examples
   :class: example

   =================  ===============  =========  =============================
       Test Case           Action      Arguments           Arguments
   =================  ===============  =========  =============================
   Simple Example     [Documentation]  LOG 1      Hello, world!
   \                  Steps            \          \
   Nested Keywords    [Documentation]  LOG 2.1    1st child of 2nd kw
   \                  Steps            \          \
   Message Index      [Documentation]  LOG 2:2    2nd msg of 2nd kw
   \                  Steps            \          \
   Nested and Index   [Documentation]  LOG 3.1:2  2nd msg of 3rd kw's 1st child
   \                  Steps            \          \
   Levels 1           [Documentation]  LOG 2      DEBUG Debug level
   \                  Steps            \          \
   Levels 2           [Documentation]  LOG 1.2:3  WARN Warning
   \                  Steps            \          \
   Multiple Messages  [Documentation]  LOG 1      First tested message
   \                  ...              LOG 1.2    Second tested message
   \                  ...              LOG 2.2.1  DEBUG Third tested message
   \                  Steps            \          \
   Status and Log     [Documentation]  FAIL       Expected error message
   \                  ...              LOG 1.2    Expected log message
   \                  Steps            \          \
   Regexp Message     [Documentation]  LOG 1      REGEXP: (Hello|Hi) world!
   \                  Steps            \          \
   No Message         [Documentation]  LOG 1:1    Test that we have only 1 msg
   \                  ...              LOG 1:2    NONE
   \                  Steps            \          \
   =================  ===============  =========  =============================
