.. _exitcode_directive:


exitcode_directive - set runtask exit code based on last or worst YAML outcome
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 0.3.18

This directives takes YAML specified by key ``result_last`` or ``result_worst`` (keys are
mutually exclusive), and generates returncode based on last or worst YAML outcome.
If YAML is empty, exitcode is set to SUCCESS.

If task formula contains multiple usages of exitcode directive, worst exitcode is returned by
runtask.

Input for directive is supposed to be in a :ref:`resultyaml-format`. The easiest way to create it
is to use :class:`.CheckDetail` objects to construct your result (or results), and then generate
the YAML output with :func:`~.check.export_YAML`.
Read more in :ref:`writing-tasks-for-taskotron`.


Parameters
----------

.. raw:: html

    <table class="rawhtml" border=1 cellpadding=4>
    <tr>
    <th class="head">parameter</th>
    <th class="head">required</th>
    <th class="head">description</th>
    <th class="head">type</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    </tr>
            <tr>
    <td class="bold"><p>result_last</p></td>
    <td>yes</td>
    <td><p>YAML output, last outcome is used. <tt class="docutils literal">result_worst</tt> cannot be specified together with this one.</p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>result_worst</p></td>
    <td>yes</td>
    <td><p>YAML output, worst outcome is used. <tt class="docutils literal">result_last</tt> cannot be specified together with this one.</p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
        </table>

Return Values
-------------

:int: Returncode based on YAML last or worst outcome. Success is ``0``, failure is ``100``.


Exceptions
----------

* :class:`.TaskotronDirectiveError`: when there's not exactly one of parameters ``result_last``
  or ``result_last`` present
* :class:`.TaskotronValueError`: when YAML input cannot be parsed



Examples
--------


Run a check returning multiple results and make ``runtask`` fail if any of the results is failed::

  - name: run my check and return YAML
    python:
        file: my_check.py
        callable: run
    export: results

  - name: set runtask exit code according to the worst result in YAML
    exitcode:
        result_worst: ${results}

Run a check that returns multiple results and one "overall" result (at the end) which is computed
according check's internal logic. Then make ``runtask`` fail if the overall result failed::

  - name: run my check and return YAML
    python:
        file: my_check.py
        callable: run
    export: results

  - name: set runtask exit code according to the last (overall) result in YAML
    exitcode:
        result_last: ${results}