results
=======

.. py:module:: results

.. autoapi-nested-parse::

   Functions and helpers for result management when working with
    - TMT (https://github.com/teemtee/tmt)
    - Beaker (https://beaker-project.org/docs/server-api/index.html)

   TMT has a 'result:custom' feature (in test's main.fmf), which allows us to
   supply completely custom results as a YAML file, and TMT will use it as-is
   to represent a result from the test itself, and any results "under" it,
   effectively allowing a test to report more than 1 result.

   Beaker uses the HTTP API, connecting to a local labcontroller.









Module Contents
---------------

.. py:class:: Counter

   Bases: :py:obj:`collections.defaultdict`


   dict() -> new empty dictionary
   dict(mapping) -> new dictionary initialized from a mapping object's
       (key, value) pairs
   dict(iterable) -> new dictionary initialized as if via:
       d = {}
       for k, v in iterable:
           d[k] = v
   dict(**kwargs) -> new dictionary initialized with the name=value pairs
       in the keyword argument list.  For example:  dict(one=1, two=2)


   .. py:method:: total()


.. py:data:: global_counts

.. py:function:: have_tmt_api()

   Return True if we can report results via TMT natively.


.. py:function:: have_beaker_api()

   Return True if we have access to Beaker results API.


.. py:function:: report_tmt(status, name=None, note=None, logs=None, *, add_output=True)

.. py:function:: report_beaker(status, name=None, note=None, logs=None)

.. py:function:: report_plain(status, name=None, note=None, logs=None)

.. py:function:: report(status, name=None, note=None, logs=None, *, add_output=True)

   Report a test result.

   'name' will be appended to the currently running test name,
   allowing the test to report one or more sub-results.
   If empty, result for the test itself is reported.

   'logs' is a list of file paths (relative to CWD) to be copied
   or uploaded, and associated with the new result.

   'add_output' specifies whether to add the test's own std* console
   output, as captured by TMT, to the list of logs whenever 'name'
   is empty.

   Returns the final 'status', potentially modified by the waiving logic.


.. py:function:: report_and_exit(status=None, note=None, logs=None)

   Report a result for the test itself and exit with 0 or 2, depending
   on whether there were any failures reported during execution of
   the test.