.. _test-file:

test-file
=========

``test_file`` loads the data from a given file path in ``file``.

Usage
-----

.. code-block:: rst

   .. test-file:: My Test Data
      :file: my_test_data.xml
      :id: TESTFILE_1


The following options can be set:

* **id**: Unique id for the test file. If not given, generated from title.
* **file**: file path to test file. If relative, the location of ``conf.py`` folder is taken as base-folder.
* **status**: A status as string.
* **tags**: A comma-separated list of strings.
* **links**: A comma-separated list of IDs to other documented test_files / needs-objects.
* **collapse**: If set to "TRUE", meta data is collapsed. Can also be set to "FALSE".
* **auto_suites**: If set (no value!), all contained suites will get documented (like using ``test-suite``).
* **auto_cases**: If set (no value!), all contained cases will get documented (like using ``test-cases``).
  Must be used together with ``auto_suites``!

``test_file`` creates a need of type ``Test-File`` and adds the following options automatically:

* **suites**: Amount of found suites in test file.
* **cases**: Amount of found cases in test file.
* **passed**: Amount of passed test cases.
* **skipped**: Amount of skipped test cases.
* **failed**: Amount of failed test cases.
* **errors**: Amount of test cases which have errors during tet execution.

These options can also be used to :ref:`filter for certain Test-Files <filter>`.

Autogenerated suites and cases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By using the options ``auto_suites`` or ``auto_cases`` Sphinx-Test-Report will documented all found suites/cases
in the given test-file.

So it will create sphinx-needs-objects, like you would manually use the directives ``test-suite`` or ``test-case``.

It uses the ID of ``test_file`` as prefix for the IDs of the suites and cases.
Their ID will be hash-value based on their title.
So a suite ID may look like ``TESTFILE1_E2A5`` and a case ID ``TESTFILE1_E2A5_F39A``.

These IDs should be stable between different sphinx builds, as long as their title of suites / cases does not change.

All other options like ``tags``, ``links``, ``status`` are copied from ``test-file`` directive to the autogenerated
``test-suite`` and ``test-case`` directives.

``links`` will also contain links to the parent objects, e.g. a ``test-case`` has links to the ``test_suite`` and also
to the ``test-file``.

Example
-------

Basics
~~~~~~

.. code-block:: rst

   .. test-file:: common xml test data
      :file: ../tests/doc_test/utils/xml_data.xml
      :id: TESTFILE_1

      This test_file has very common data.
      Some options are net set, therefore their value is ``-1``

   .. test-file:: pytest test data
      :file: ../tests/doc_test/utils/pytest_data.xml
      :id: TESTFILE_2
      :links: TESTFILE_1

      This test_file was created by `pytest <https://docs.pytest.org/en/latest/>`_.

   .. test-file:: nose test data
      :file: ../tests/doc_test/utils/nose_data.xml
      :id: TESTFILE_3
      :links: TESTFILE_1
      :status: open
      :tags: pytest, data, awesome
      :collapse: FALSE

      This test_file was created by `nosetest <https://nose.readthedocs.io/en/latest/>`_.

      ``collapse`` was set to False, therefor we see its data directly.
      Also ``status`` and ``tags`` are set.


.. test-file:: common xml test data
   :file: ../tests/doc_test/utils/xml_data.xml
   :id: TESTFILE_1

   This test_file has very common data.
   Some options are not set, therefore their value is ``-1``

.. test-file:: pytest test data
   :file: ../tests/doc_test/utils/pytest_data.xml
   :id: TESTFILE_2
   :links: TESTFILE_1

   This test_file was created by `pytest <https://docs.pytest.org/en/latest/>`_.

.. test-file:: nose test data
   :file: ../tests/doc_test/utils/nose_data.xml
   :id: TESTFILE_3
   :links: TESTFILE_1
   :status: open
   :tags: pytest, data, awesome
   :collapse: FALSE

   This test_file was created by `nosetest <https://nose.readthedocs.io/en/latest/>`_.

   ``collapse`` was set to False, therefor we see its data directly.
   Also ``status`` and ``tags`` are set.

Autogenerated suite
~~~~~~~~~~~~~~~~~~~~

.. code-block:: rst

   .. test-file:: pytest test data
      :file: ../tests/doc_test/utils/pytest_data.xml
      :id: TESTFILE_AUTO1
      :auto_suites:
      :collapse: FALSE
      :tags: auto


.. test-file:: pytest test data
   :file: ../tests/doc_test/utils/pytest_data.xml
   :id: TESTFILE_AUTO1
   :auto_suites:
   :collapse: FALSE
   :tags: auto

Autogenerated suite and cases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: rst

   .. test-file:: pytest test data
      :file: ../tests/doc_test/utils/pytest_data.xml
      :id: TESTFILE_AUTO2
      :auto_suites:
      :auto_cases:
      :tags: auto


.. test-file:: pytest test data
   :file: ../tests/doc_test/utils/pytest_data.xml
   :id: TESTFILE_AUTO2
   :auto_suites:
   :auto_cases:
   :tags: auto