Requirements Coverage
=====================

.. _requirements:

The Dashboard is able to track requirements and create requirements coverage graphs.
You can test requirements in different ways.

Adding Requirements using HILSTER Testing Framework
---------------------------------------------------

Requirements can be added to tests using HILSTER Testing Framework's :func:`htf.requirements` decorator.

.. code-block:: python

    @htf.requirements('REQ-1', 'REQ-2', 'REQ-3')
    def test_with_requirements(step):
        with step("This is the first test step"):
            pass


Adding Requirements with other Tools
------------------------------------

Alternatively requirements can be printed to stdout and stderr so that requirements
can be extracted from all types of test reports, i.e. JUnit-XML, etc.
Thus the Dashboard allows requirements coverage with any kind of testing framework
that supports JUnit-XML reports.

Printed requirements must fulfill the following rules:

 - Each requirement is printed on a single line.
 - Each line containing a requirement contains

    ``REQUIREMENT``,

    ``REQ`` or

    ``FULFILLS``, followed by a colon (``:``) and

     - at least one space followed by the requirement name itself.

 - Each requirement name consists of at least one characters out of ``A-Z``, ``0-9``, ``-``, ``_`` and ``.``.

 - Requirements are case-insensitive.

.. code-block:: python

    def test_with_printed_requirementsref():
        print("REQ: REQ-1")
        print("REQUIREMENT: REQ-2")
        print("FULLFILLS: REQ-3")

.. _submitting-requirements:

Submitting Requirements
-----------------------

Requirements can be submitted to the dashboard using the command line interface.

Requirement files need to be ``csv``-files with an arbitrary header line and
the requirement IDs located in the leftmost column. The first line, the header line, is ignored. E.g.:

.. code-block::

    ID, ...
    REQ-0, ...
    REQ-1, ...
    .
    .

The included requirements in this case would be ``REQ-0``, ``REQ-1``, ``...``.

Multi-line values are supported using ``"`` as quotechar:

.. code-block::

    ID,Content,Last-Modified
    REQ-0,Content for REQ-0,2100-01-01
    REQ-1,Content for REQ-1,2100-01-01
    REQ-2,"Content for
    REQ-2",2100-01-01
    REQ-3,Content for REQ-2,2100-01-01
    .
    .

In the user-interface the column with the longest entry will be used as the content.

Learn how to :ref:`upload requirements<upload-requirements>` via the command line interface.