test-file¶
test-file loads the data from a given file path in file.
Usage¶
.. 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.pyfolder 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 withauto_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 filter for certain test-files.
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.
You can add custom options to the test-file directive by configuring the tr_extra_options value in your conf.py.
These must also be defined in either needs_extra_options or needs_extra_links.
Example¶
Basics¶
.. 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.
This test-file has very common data.
Some options are not set, therefore their value is |
This test-file was created by pytest. |
This test-file was created by nosetest.
|
Autogenerated suite¶
.. 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¶
.. test-file:: pytest test data
:file: ../tests/doc_test/utils/pytest_data.xml
:id: TESTFILE_AUTO2
:auto_suites:
:auto_cases:
:tags: auto
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |
Text: Message: |