testsuite.driver
================

.. py:module:: testsuite.driver


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/testsuite/driver/adacore/index
   /autoapi/testsuite/driver/classic/index
   /autoapi/testsuite/driver/diff/index


Attributes
----------

.. autoapisummary::

   testsuite.driver.ResultQueue


Classes
-------

.. autoapisummary::

   testsuite.driver.ResultQueueItem
   testsuite.driver.TestDriver
   testsuite.driver.BasicTestDriver


Package Contents
----------------

.. py:class:: ResultQueueItem

   Information to integrate a test result in a testsuite report.

   Test drivers create test results. They travel from there to the testsuite
   final report through various queues. This class gathers all the information
   needed for the various stages of this pipeline.


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

      Name of the test that created this test result.



   .. py:attribute:: result
      :type:  e3.testsuite.result.TestResultSummary

      Summary for this test result.



   .. py:attribute:: filename
      :type:  str

      Name of the file that contains test result data.



   .. py:attribute:: traceback
      :type:  List[str]

      Stack trace for this result's push time.

      This stack trace corresponds to the code that led the TestResult instance
      to be included in the testsuite report.



   .. py:attribute:: gaia_results
      :type:  Optional[e3.testsuite.report.gaia.GAIAResultFiles]

      GAIA files for this result.

      This is None if no GAIA report is requested.



.. py:data:: ResultQueue

.. py:class:: TestDriver(env: e3.env.Env, test_env: Dict[str, Any])

   Bases: :py:obj:`object`


   Testsuite Driver.

   All drivers declared in a testsuite should inherit from this class


   .. py:attribute:: Fore
      :type:  Any


   .. py:attribute:: Style
      :type:  Any


   .. py:attribute:: test_env_filename
      :type:  str


   .. py:attribute:: env
      :type:  e3.env.Env


   .. py:attribute:: testsuite_options
      :type:  argparse.Namespace


   .. py:attribute:: test_env
      :type:  Dict[str, Any]


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


   .. py:attribute:: result
      :type:  e3.testsuite.result.TestResult


   .. py:attribute:: result_queue
      :type:  ResultQueue
      :value: []


      Queue of test results that this driver plans to integrate to the
      testsuite report.



   .. py:attribute:: execution_started
      :type:  bool
      :value: False


      Whether the execution of at least one fragment for this test driver has
      started.



   .. py:attribute:: pending_fragments
      :type:  set[str]

      Set of UIDs for fragments whose execution has not yet completed for
      this test driver.



   .. py:method:: push_result(result: Optional[e3.testsuite.result.TestResult] = None) -> None

      Push a result to the testsuite.

      This method should be called to push results to the testsuite report.

      :param result: A TestResult object to push. If None push the current
          test result.



   .. py:method:: add_fragment(dag: e3.collection.dag.DAG, name: str, fun: Optional[e3.testsuite.fragment.FragmentCallback] = None, after: Optional[List[str]] = None) -> None

      Add a test fragment.

      This function is a helper to define test workflows that do not
      introduce dependencies to other tests. For more complex operation use
      directly add_vertex method from the dag. See add_test method.

      :param dag: DAG containing test fragments.
      :param name: Name of the fragment.
      :param fun: Callable that takes two positional arguments: a mapping
          from fragment names to return values for already executed
          fragments, and a slot ID. If None looks for a method inside this
          class called ``name``.
      :param after: List of fragment names that should be executed before
          this one.



   .. py:method:: working_dir(*args: str) -> str

      Build a filename in the test working directory.



   .. py:method:: test_dir(*args: str) -> str

      Build a filename in the testcase directory.



   .. py:method:: add_test(dag: e3.collection.dag.DAG) -> None
      :abstractmethod:


      Create the test workflow.

      Amend a DAG with the test fragments that should be executed along with
      their dependencies. See BasicTestDriver for an example of workflow.



   .. py:property:: working_dir_cleanup_enabled
      :type: bool


      Return whether test drivers should cleanup their working directory.

      Unless this returns False, test drivers should delete their working
      directory when the test has completed, so that temporaries for the
      whole testsuite are removed incrementally. This is necessary to avoid
      creating huge temporary directories when executing big testsuites.



.. py:class:: BasicTestDriver(env: e3.env.Env, test_env: Dict[str, Any])

   Bases: :py:obj:`TestDriver`


   Testsuite Driver.

   All drivers declared in a testsuite should inherit from this class


   .. py:method:: add_test(dag: e3.collection.dag.DAG) -> None

      Create a standard test workflow.

      set up -> run -> analyze -> tear_down in which set up and tear_down
      are optional.



   .. py:method:: set_up(prev: Dict[str, Any], slot: int) -> None

      Execute operations before executing a test.



   .. py:method:: tear_up(prev: Dict[str, Any], slot: int) -> None

      Backwards-compatible name for the "set_up" method.



   .. py:method:: tear_down(prev: Dict[str, Any], slot: int) -> None

      Execute operations once a test is finished.



   .. py:method:: run(prev: Dict[str, Any], slot: int) -> None
      :abstractmethod:


      Execute a test.



   .. py:method:: analyze(prev: Dict[str, Any], slot: int) -> None
      :abstractmethod:


      Compute the test result.