# Filtering Test Data¶

You can filter the documented test-data by using the directives needlist, needtable and needflow.

These filter functions and others are provided by the Sphinx extension Sphinx-Needs. Take a look to figure out what else is possible to customize your way of working with test cases.

## Filterable data¶

Sphinx-Test-Reports adds to following data to a sphinx-need-configuration:

• Types

• test-file

• test_suite

• test_case

• Options

• file: Test file path.

• suite: Test suite name.

• case: Test case name.

• suites: Amount of test suites found inside a test file.

• cases: Amount of test cases found inside a test file.

• passed: Amount of passed test cases.

• skipped: Amount of skipped test cases.

• errors: Amount of test cases with errors during execution.

• failed: Amount of failed test cases.

Not all options are set for all created needs. E.g. test_file doesn’t include case, as it is not related to a single test case.

The filtering possibilities are really powerful, so take a look into Filtering needs to figure out how to get most out of your test data.

## needtable - A table for all tests¶

needtable provides a feature-rich table of the needed test data.

Use it like:

.. needtable::
:types: Test-File
:columns: id, file, suites, cases, passed


We set types to test_file to document needs-objects from this type only. Sphinx-Test-Reports provides also test_suite and test_case.

With columns we can specify which data of a test_file we want to see.

Example

ID

File

Suites

Cases

Passed

TESTFILE_1

../tests/data/xml_data.xml

1

3

3

TESTFILE_2

../tests/data/pytest_data.xml

1

10

0

TESTFILE_3

../tests/data/nose_data.xml

1

5

5

TESTFILE_AUTO1

../tests/data/pytest_data.xml

1

10

0

TESTFILE_AUTO2

../tests/data/pytest_data.xml

1

10

0

REPORT

1

7

4

CASPERJS_001

../tests/data/casperjs.xml

37

241

241

PYTEST01

../tests/data/pytest_data.xml

1

10

0

NOSE01

../tests/data/nose_data.xml

1

5

5

SPHINX

../tests/data/pytest_sphinx_data.xml

1

1152

1146

## needlist - A simple list¶

needlist provides a simple list of the filtered test-needs.

The filter possibilities are the same as for needtable and needflow.

Usage:

.. needlist::
:types: Test-File
:filter: cases.isdigit() and int(cases) > 4


filter supports complex-filter operations by using a Python-statement. In this case, we check that the cases value contains a number and this number must ne bigger as 4.

Take a look into the Filter string section of the Sphinx-Needs documentations for more details and ideas how to use it.

Example

## needflow - Flow charts of linked test data¶

needflow draws a picture of the filtered need-objects and their connections/links.

Note

This features needs the installed and configured sphinx-extension sphinxcontrib-plantuml.

Usage:

.. needflow::
:types: Test-File, Test-Suite, Test-Case

The used :filter: allows needs only, if they have an outgoing or incoming link.