[test_reports]

The test-report settings shared with sphinx-test-reports and its test-reports converter, which read this same section.

When this table is present (even empty), the test-file, test-suite and test-case need types and the fields their needs carry are added to the project’s needs configuration, so a needs.json written by the converter imports without declaring them. A need type the project declares itself under the same name is kept as declared. Keys this version does not read are ignored with a warning; a key of the wrong type is an error.

Guide: Test reports.

test_reports.build
Type:
table

Settings of the test-reports build command line, one table per output it produces.

test_reports.build.needs
Type:
table

How test-reports build needs writes a needs.json.

test_reports.build.needs.commit
Type:
string
Default:
""

The commit source links point at. Used by the test-reports build needs converter; a CI job usually passes it on the command line instead.

Type:
table of strings

Deprecated spelling of [test_reports] property_link_types, read when that key is not set (a warning when both are set and differ). Both names in each pair must be non-empty.

test_reports.build.needs.need_type
Type:
string
Default:
"testcase"

The need type every test case gets. Must equal the type of [test_reports] case.

test_reports.build.needs.project
Type:
string
Default:
""

The project written into the needs.json.

test_reports.build.needs.remote_url
Type:
string
Default:
""

The repository URL source links are made from. Used by the test-reports build needs converter; a CI job usually passes the commit on the command line.

test_reports.build.needs.tags
Type:
array of strings
Default:
[]

Tags added to every test case need.

test_reports.build.needs.url_pattern
Type:
string
Default:
"{base}/blob/{commit}/{file}#L{line}"

The source link pattern, from the placeholders {base}, {commit}, {file} and {line}. A pattern that cannot make a link is reported.

test_reports.build.needs.version
Type:
string
Default:
"1.0"

The version the needs are written under.

test_reports.case
Type:
table or array of strings

The test-case directive and need type, spelled as file is.

Unset, and for each key a table leaves out: test-case, testcase, Test-Case, TC_, #999999, rectangle. Its type must equal [test_reports.build.needs] need_type when that table is present.

Forms:

  • a table: The named spelling.

  • an array of strings: The positional spelling: exactly six strings.

test_reports.case.color
Type:
string

The need type’s color.

test_reports.case.directive
Type:
string

The directive name.

test_reports.case.name
Type:
string

The need type’s title.

test_reports.case.prefix
Type:
string

The need type’s id prefix.

test_reports.case.style
Type:
string

The need type’s diagram style.

test_reports.case.type
Type:
string

The need type the directive creates.

test_reports.case_id_length
Type:
integer
Default:
5

How many characters of a test case’s hash an automatic case id keeps: the id of each case need a test-file with :auto_cases: creates, unless deterministic_case_ids is on.

test_reports.deterministic_case_ids
Type:
boolean
Default:
false

Whether automatic test-case ids use the deterministic scheme (<type>__<class>__<name>_<five letters>, the one the converter always writes) instead of the legacy hashed one: for a test-case without :id: and for each case need of :auto_cases:.

test_reports.extra_options
Type:
array of strings
Default:
[]

Test properties that become need fields: each name is added as a string field, and a property of that name is copied into it.

test_reports.file
Type:
table or array of strings

The test-file directive and need type: a table of directive, type, name, prefix, color and style, or those six strings as an array, in that order.

Unset, and for each key a table leaves out: test-file, testfile, Test-File, TF_, #ffffff, node. Renaming the directive is not supported yet (a warning; the directive keeps its default name).

Forms:

  • a table: The named spelling.

  • an array of strings: The positional spelling: exactly six strings.

test_reports.file.color
Type:
string

The need type’s color.

test_reports.file.directive
Type:
string

The directive name.

test_reports.file.name
Type:
string

The need type’s title.

test_reports.file.prefix
Type:
string

The need type’s id prefix.

test_reports.file.style
Type:
string

The need type’s diagram style.

test_reports.file.type
Type:
string

The need type the directive creates.

test_reports.file_option
Type:
string
Default:
"file"

The need field holding the test report’s path.

It must not name a field every test-case need already has, nor the same field as source_file_option or source_line_option. Empty means the default.

test_reports.import_encoding
Type:
string
Default:
"utf8"

The text encoding of the report template.

test_reports.json_mapping
Type:
table

How the fields of a JSON test report are found.

Accepted and kept, but JSON test reports are not read yet.

Type:
table of strings
Default:
{}

Test properties whose values become links: a table from a property name to the link field it fills.

links is always available; any other target must be a declared link type (a warning otherwise). When unset, [test_reports.build.needs] link_properties is used if set.

test_reports.report_template
Type:
string

The template a test-report directive renders.

A relative path is taken from the directory of the configuration file that sets it. Unset or "", the template shipped with sphinx-test-reports.

test_reports.rootdir
Type:
string

The directory relative report paths are read from.

A relative path is taken from the directory of the configuration file that sets it. Unset, the project’s source directory ([source] dir, or this file’s directory) is used.

test_reports.source_file_option
Type:
string
Default:
"case_file"

The need field holding the test’s source file, under the same rules as file_option.

test_reports.source_line_option
Type:
string
Default:
"case_line"

The need field holding the test’s line in its source file, under the same rules as file_option.

test_reports.suite
Type:
table or array of strings

The test-suite directive and need type, spelled as file is.

Unset, and for each key a table leaves out: test-suite, testsuite, Test-Suite, TS_, #cccccc, folder.

Forms:

  • a table: The named spelling.

  • an array of strings: The positional spelling: exactly six strings.

test_reports.suite.color
Type:
string

The need type’s color.

test_reports.suite.directive
Type:
string

The directive name.

test_reports.suite.name
Type:
string

The need type’s title.

test_reports.suite.prefix
Type:
string

The need type’s id prefix.

test_reports.suite.style
Type:
string

The need type’s diagram style.

test_reports.suite.type
Type:
string

The need type the directive creates.

test_reports.suite_id_length
Type:
integer
Default:
3

How many characters of a test suite’s hash an automatic suite id keeps: the id of each suite need a test-file with :auto_suites: creates. Raise it when two suite names get the same id.