.. Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2016. Part of Pathways project -*- coding: utf-8 -*-

.. highlight:: shell-session

.. The inline fragments are shell/console commands. The Python code-fragments are specified with a ‘code-block’ directive

How to run ATSes?
#################

There are several ways to run :term:`ATS`\es. There is no *best* way, that is very depending of the goal and the
project. This chapter gives an overview of the options; so you can select the one that fits you best. But remember, you can
easily add or combine options.

Using :command:`pw`
===================

Pathways comes with a tool :doc:`ManualPages/pw` to run one or more :term:`ATSfile`\s from the command-line.::

   [albert@pathways:tst]%  pw  ATS/demo1.py
   ...
   Final Test result: OK (after 1 ATS)
   [albert@pathways:tst]%  pw  ATS/demo1 ATS/demo2.py
   ...
   Final Test result: OK (after 2 ATSes)

As the configuration is read before the :term:`ATS` is loaded, the :term:`ATS` may use import modules (like plugins)
from non-standard locations, without setting :envvar:`PYTHONPATH`.

.. tip:: The ``.py`` extension in the named :term:`ATS`\es are optional, as shown above


Use  :py:func:`pathways.autorun` *(run the ATS itself)*
=======================================================

Most :term:`ATS`\es can be started by executing that file. Only the :term:`ATStest`\s in that file are executed.::

   [albert@pathways:tst]%  ./ATS/demo3.py
   ...
   Final Test result: OK (after 1 ATS)

Typically it is called from the :file:`tst` directory; to make sure all relative paths are correct.

.. attention::

   To enable this, each :term:`ATSfile` should call :py:func:`pathways.autorun` as main routine. As shown in the following code fragment

   .. code-block:: python3

      if __name__ == "__main__":
         exit(pathways.autorun())

   To make sure the exit-code is correctly set, the :py:func:`pathways.autorun` should be wrapped in :py:func:`exit`


Interactively in Jupyter (IPython) Notebook
===========================================

It is possible to develop and/or run ATS in Jupyter Notebook (or directly in IPython).

.. seealso:: For now, see  http://localhost:8887/notebooks/Pathways/RunATSes_from_Notebook.ipynb

.. todo:: This runner need work; the link above is a HACK


More to follow
==============

There should be options to integrate running the :term:`ATS`\es within other frameworks, like:

* cronstab
* nightly build
* continues integration tools
* build tools,
* etc

During such an automatic-run, it should be possible to select tests, determine the order and to determine how to
continue after an failure.

This work to be planned. For now, some simple shell (or python) script will do.