e3.testsuite.result
===================

.. py:module:: e3.testsuite.result

.. autoapi-nested-parse::

   Data structures for testcase execution results.



Attributes
----------

.. autoapisummary::

   e3.testsuite.result._test_status_tag
   e3.testsuite.result._failure_reason_tag


Classes
-------

.. autoapisummary::

   e3.testsuite.result.TestStatus
   e3.testsuite.result.FailureReason
   e3.testsuite.result.Log
   e3.testsuite.result.TestResult
   e3.testsuite.result.TestResultSummary


Functions
---------

.. autoapisummary::

   e3.testsuite.result.binary_repr
   e3.testsuite.result.truncated
   e3.testsuite.result._log_representer
   e3.testsuite.result._test_status_constructor
   e3.testsuite.result._test_status_representer
   e3.testsuite.result._failure_reason_constructor
   e3.testsuite.result._failure_reason_representer


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

.. py:class:: TestStatus(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Testcase execution status.


   .. py:attribute:: PASS


   .. py:attribute:: FAIL


   .. py:attribute:: XFAIL


   .. py:attribute:: XPASS


   .. py:attribute:: VERIFY


   .. py:attribute:: SKIP


   .. py:attribute:: NOT_APPLICABLE


   .. py:attribute:: ERROR


   .. py:method:: color(colors: e3.testsuite.utils.ColorConfig) -> str

      Return the ANSI color code for this test status.

      This returns an empty string if colors are disabled.



.. py:class:: FailureReason(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Reason for a test failure.


   .. py:attribute:: CRASH


   .. py:attribute:: TIMEOUT


   .. py:attribute:: MEMCHECK


   .. py:attribute:: DIFF


.. py:class:: Log(content: AnyStr)

   Bases: :py:obj:`yaml.YAMLObject`, :py:obj:`Generic`\ [\ :py:obj:`AnyStr`\ ]


   Object to hold long text or binary logs.

   We ensure that when dump to yaml the result will be human readable.


   .. py:attribute:: yaml_loader


   .. py:attribute:: yaml_tag
      :value: '!e3.testsuite.result.Log'



   .. py:attribute:: log
      :type:  AnyStr


   .. py:property:: is_binary
      :type: bool


      Return whether this log contains binary data.



   .. py:property:: is_text
      :type: bool


      Return whether this log contains text data.



   .. py:method:: __iadd__(content: AnyStr) -> Log[AnyStr]

      Add additional content to the log.

      :param content: a message to log



   .. py:method:: __str__() -> str


.. py:function:: binary_repr(binary: bytes) -> str

   Return a human readable representation for the given bytes string.

   This just decodes ASCII printable bytes and newlines to the corresponding
   strings and represents other bytes with the "\xXX" escapes.

   :param binary: Bytes string to represent.


.. py:function:: truncated(output: str, line_count: int) -> str

   Truncate an output not to exceed twice the given number of lines.

   If ``output`` has more than ``2 * line_count`` lines, only keep the first
   ``N`` and last ``N`` lines of it. Return it unchanged otherwise, or if
   ``line_count`` is 0.

   :param output: Output to (maybe) truncate.
   :param line_count: Half the maximum number of lines to keep.


.. py:class:: TestResult(name: str, env: Optional[dict] = None, status: Optional[TestStatus] = None, msg: str = '')

   Bases: :py:obj:`yaml.YAMLObject`


   Represent a result for a given test.


   .. py:attribute:: yaml_loader


   .. py:attribute:: yaml_tag
      :value: '!e3.testsuite.result.TestResult'



   .. py:attribute:: test_name


   .. py:attribute:: env
      :value: None



   .. py:attribute:: status


   .. py:attribute:: msg
      :type:  Optional[str]
      :value: ''



   .. py:attribute:: log


   .. py:attribute:: processes
      :type:  list
      :value: []



   .. py:attribute:: failure_reasons
      :type:  Set[FailureReason]


   .. py:attribute:: expected
      :type:  Optional[Log]
      :value: None



   .. py:attribute:: out
      :type:  Optional[Log]
      :value: None



   .. py:attribute:: diff
      :type:  Optional[Log]
      :value: None



   .. py:attribute:: time
      :type:  Optional[float]
      :value: None



   .. py:attribute:: info
      :type:  Dict[str, str]


   .. py:method:: set_status(status: TestStatus, msg: Optional[str] = '') -> None

      Update the test status.

      :param status: New status. Note that only test results with status set
          to ERROR can be changed.
      :param msg: Optional short message to describe the result.  Note that
          multiline strings are turned into single-line strings.



   .. py:method:: __str__() -> str


   .. py:method:: save(results_dir: str) -> str

      Write this test results as a YAML file.

      :param results_dir: Name of the directory in which to write the test
          result. When writing a testsuite report, this corresponds to the
          report's ``results_dir`` (see
          ``e3.testsuite.report.index.ReportIndex``).
      :return: The base filename of the file written. It is generated from
          the testname.



   .. py:property:: summary
      :type: TestResultSummary



.. py:function:: _log_representer(dumper: Any, data: Log) -> Any

.. py:data:: _test_status_tag
   :value: '!e3.testsuite.result.TestStatus'


.. py:data:: _failure_reason_tag
   :value: '!e3.testsuite.result.FailureReason'


.. py:function:: _test_status_constructor(self: Any, node: Any) -> Iterator[Any]

.. py:function:: _test_status_representer(dumper: Any, data: TestStatus) -> Any

.. py:function:: _failure_reason_constructor(self: Any, node: Any) -> Iterator[Any]

.. py:function:: _failure_reason_representer(dumper: Any, data: FailureReason) -> Any

.. py:class:: TestResultSummary

   Basic data about a test result.

   This class holds a subset of the information available in ``TestResult``
   instances. This subset is meant to be small enough to be included in result
   indexes while enabling efficient common processings such as "show logs for
   tests that failed": no need to load all the test results for tests that
   succeeded.


   .. py:attribute:: test_name
      :type:  str


   .. py:attribute:: status
      :type:  TestStatus


   .. py:attribute:: msg
      :type:  Optional[str]


   .. py:attribute:: failure_reasons
      :type:  Set[FailureReason]


   .. py:attribute:: time
      :type:  Optional[float]


   .. py:attribute:: info
      :type:  Dict[str, str]


