.. _dummy_directive:


dummy_directive - test how directives work
++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 0.4

This is just what it sounds like - a directive that doesn't do anything other
than (optionally) return a message or raise an error. It is primarially meant
for testing the runner or as a placeholder while writing new tasks. Or you can
play with it to learn the directive basics.


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>msg</p></td>
    <td>no</td>
    <td><p>arbitrary string. If it is present, it is returned.</p></td>
    <td><p>anything</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>result</p></td>
    <td>yes</td>
    <td><p>arbitrary string. If it equals <tt class="docutils literal">FAIL</tt> (case ignored), then the directive raises an error.</p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
        </table>

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

Either ``msg``, if it was provided, or ``None``.


Exceptions
----------

* :class:`.TaskotronDirectiveError`: if ``result="FAIL"`` (case ignored)



Examples
--------


This simply returns ``msg`` that was provided::

 - name: return Koji build (NVR)
   dummy:
     result: PASS
     msg: ${koji_build}

This raises an error, regardless of whether or what was provided in ``msg``::

 - name: raise an error
   dummy:
     result: FAIL