pyTooling.Sphinx.Unittest

A directive rendering a unit test report as a table: per testsuite and testcase, the counts and the runtime.

The reports are read by pyEDAA.Reports: a JUnit XML file in any dialect - e.g. the reports of pytest or OSVVM -, or a test report in pyTooling’s own XML format, recognized by its root element <TestReport>. The report files are declared in conf.py under pyTooling_Unittest_Testsuites, each with an identifier a directive names in its :reportid: option. An entry with the key pages gets a page per testsuite and testcase, generated below that document name (see pyTooling.Sphinx.UnittestPages):

# doc/conf.py
pyTooling_Unittest_Testsuites = {
  "src": {
    "xml_report": "../report/unit/unittest.xml",
    "pages":      "unittests/src",
  }
}

The reports are read once, when the builder is initialized, and shared by every directive and page using them.

The table’s columns after the first are Column and ColumnGroup instances. A directive of another kind of test report - e.g. a simulation framework’s build summary - derives from UnittestSummaryBase, which renders the rows, and declares its own columns.

See also

report:unittest-summary

→ The directive’s options and configuration, with examples.

Variables

Classes

  • TestsuiteConfiguration: An entry of pyTooling_Unittest_Testsuites, after UnittestSummary.CheckConfiguration() read it.

  • ShowTestcases: Which testcases a unit test summary lists, by their status.

  • Column: A column of a unit test summary table: its title, its width, and the cells it adds to the rows.

  • ColumnGroup: A group of columns of a unit test summary table, under a common title: the table’s header gets a second row.

  • UnittestSummaryBase: Base-class of a directive rendering a testsuite summary - unit test results - as a table, per testsuite and testcase.

  • UnittestSummary: The report:unittest-summary directive: a table of a unit test report, per testsuite and testcase.

Variables

pyTooling.Sphinx.Unittest.CONFIG_PREFIX

Prefix every configuration value of the unit test directive carries in conf.py.

'pyTooling_Unittest'
pyTooling.Sphinx.Unittest.REPORT_FORMATS

The report formats, by the root element of a report file.

{'TestReport': 'pyTooling', 'testsuite': 'JUnit', 'testsuites': 'JUnit'}

Classes

class pyTooling.Sphinx.Unittest.TestsuiteConfiguration[source]

An entry of pyTooling_Unittest_Testsuites, after UnittestSummary.CheckConfiguration() read it.

Inheritance

Inheritance diagram of TestsuiteConfiguration

xml_report: Path

The unit test report, in JUnit XML or pyTooling’s XML format.

pages: str | None

Document name the pages per testsuite and testcase are generated below, if any.

__contains__(key, /)

True if the dictionary has the specified key, else False.

__delitem__(key, /)

Delete self[key].

__eq__(value, /)

Return self==value.

__ge__(value, /)

Return self>=value.

__getitem__(key, /)

Return self[key].

__gt__(value, /)

Return self>value.

__init__(*args, **kwargs)
__ior__(value, /)

Return self|=value.

__iter__()

Implement iter(self).

__le__(value, /)

Return self<=value.

__len__()

Return len(self).

__lt__(value, /)

Return self<value.

__ne__(value, /)

Return self!=value.

classmethod __new__(*args, **kwargs)
__or__(value, /)

Return self|value.

__repr__()

Return repr(self).

__reversed__()

Return a reverse iterator over the dict keys.

__ror__(value, /)

Return value|self.

__setitem__(key, value, /)

Set self[key] to value.

__sizeof__()

Return the size of the dict in memory, in bytes.

clear()

Remove all items from the dict.

copy()

Return a shallow copy of the dict.

classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items()

Return a set-like object providing a view on the dict’s items.

keys()

Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

Return an object providing a view on the dict’s values.

class pyTooling.Sphinx.Unittest.ShowTestcases(*values)[source]

Which testcases a unit test summary lists, by their status.

A member compares equal to a TestcaseStatus it includes.

Inheritance

Inheritance diagram of ShowTestcases

passed = 1

Passed testcases, and testcases failing as expected.

failed = 2

Failed testcases, and testcases passing unexpectedly.

skipped = 4

Skipped testcases.

excluded = 8

Excluded testcases.

errors = 16

Errored testcases, and testcases whose setup failed.

aborted = 32

Aborted testcases.

all = 63

Every testcase.

not_passed = 62

Every testcase but the passed ones.

__eq__(other)[source]

Check whether a testcase status is included.

Parameters:

other (Any) – A testcase status.

Return type:

bool

Returns:

True if other is a TestcaseStatus this member includes.

class pyTooling.Sphinx.Unittest.Column(title, width=None, *, testsuite=None, testcase=None)[source]

A column of a unit test summary table: its title, its width, and the cells it adds to the rows.

A row shows a testsuite summary, a testsuite or a testcase. A column names a function per kind of row, which returns the cell’s content: a text, a node, or the cell itself - an entry, e.g. to give it a CSS class. A column without a function for a kind of row leaves the cell of such a row empty.

Inheritance

Inheritance diagram of Column

Parameters:

  • title (str)

  • width (Nullable[int])

  • testsuite (Nullable[Callable[[TestsuiteBase[Any]], str | nodes.Node]])

  • testcase (Nullable[Callable[[Testcase], str | nodes.Node]])

__init__(title, width=None, *, testsuite=None, testcase=None)[source]

Initializes a column of a unit test summary table.

Parameters:

  • title (str) – Title of the column.

  • width (int | None) – Optional, relative width of the column; None leaves it to the writer. Default: None.

  • testsuite (Callable[[TestsuiteBase[Any]], str | Node] | None) – Optional, function returning the content of the cell of a testsuite’s row and of a testsuite summary’s rows. Default: None.

  • testcase (Callable[[Testcase], str | Node] | None) – Optional, function returning the content of the cell of a testcase’s row. Default: None.

Raises:

  • ValueError – If parameter ‘title’ is None.

  • TypeError – If parameter ‘title’ is not of type str.

  • TypeError – If parameter ‘width’ is not of type int.

  • TypeError – If parameter ‘testsuite’ is not callable.

  • TypeError – If parameter ‘testcase’ is not callable.

Return type:

None

_title: str

Title of the column.

_width: int | None

Relative width, or None.

_testsuite: Callable[[TestsuiteBase[Any]], str | Node] | None

Content of a testsuite(‘s summary) row.

_testcase: Callable[[Testcase], str | Node] | None

Content of a testcase’s row.

property Title: str

Read-only property to access the column’s title (_title).

Returns:

The title.

property Width: int | None

Read-only property to access the column’s relative width (_width).

Returns:

The width, or None if the writer chooses it.

TestsuiteCell(testsuite)[source]

Create the column’s cell of a testsuite’s row, or of a testsuite summary’s row.

Parameters:

testsuite (TestsuiteBase[Any]) – The testsuite or testsuite summary.

Return type:

entry

Returns:

The cell.

TestcaseCell(testcase)[source]

Create the column’s cell of a testcase’s row.

Parameters:

testcase (Testcase) – The testcase.

Return type:

entry

Returns:

The cell.

static _Cell(function, entity)[source]

Create a cell from the content a function returns for a row’s testsuite or testcase.

Parameters:

  • function (Callable[[Any], str | Node] | None) – The function, or None for an empty cell.

  • entity (Any) – The row’s testsuite, testsuite summary or testcase.

Return type:

entry

Returns:

The cell.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

class pyTooling.Sphinx.Unittest.ColumnGroup(title, columns)[source]

A group of columns of a unit test summary table, under a common title: the table’s header gets a second row.

Inheritance

Inheritance diagram of ColumnGroup

Parameters:
__init__(title, columns)[source]

Initializes a group of columns.

Parameters:

  • title (str) – Title of the group.

  • columns (Iterable[Column]) – The grouped columns.

Raises:

  • ValueError – If parameter ‘title’ is None.

  • TypeError – If parameter ‘title’ is not of type str.

  • ValueError – If parameter ‘columns’ is None.

  • TypeError – If parameter ‘columns’ is not iterable.

  • TypeError – If parameter ‘columns’ contains an element not of type Column.

  • ValueError – If parameter ‘columns’ is empty.

Return type:

None

_title: str

Title of the group.

_columns: tuple[Column, ...]

The grouped columns.

property Title: str

Read-only property to access the group’s title (_title).

Returns:

The title.

property Columns: tuple[Column, ...]

Read-only property to access the grouped columns (_columns).

Returns:

The columns, in their order in the table.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

class pyTooling.Sphinx.Unittest.UnittestSummaryBase(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Base-class of a directive rendering a testsuite summary - unit test results - as a table, per testsuite and testcase.

The table has a row per testsuite and listed testcase, indented by its depth, optionally a row of the testsuite summary above them, and a row of the overall status below them. Its first column names the row - linked to the row’s page, if the report has pages -, the other columns are the Column and ColumnGroup instances _Columns() returns.

The report files are declared in a configuration value of conf.py (_CONFIG_VALUE), each with an identifier, the report file (key _REPORT_KEY) and optionally the key pages. A derived class names them, declares its own class variables _testSummaries, _reports and _readErrors, reads a report file by _ReadReport(), reads its options in _CheckOptions(), and returns its pages by _Pages().

A legend of the status symbols (_LEGEND) is drawn below the table, or above it or not at all, as option :legend: chooses; a derived class accepts the option by adding "legend": LegendPosition.Parse to its option_spec.

Inheritance

Inheritance diagram of UnittestSummaryBase

_CONFIG_VALUE: ClassVar[str]

Configuration value declaring the reports.

_REPORT_KEY: ClassVar[str]

Key of a report’s file, e.g. xml_report.

_REPORT_KIND: ClassVar[str]

Kind of report, e.g. Unittest report.

_NAME_COLUMN: ClassVar[Column] = <pyTooling.Sphinx.Unittest.Column object>

The first column, naming the rows.

_testSummaries: ClassVar[dict[str, dict[str, Any]]]

Report configurations, by report ID.

_reports: ClassVar[dict[str, TestsuiteSummary]]

Reports read by ReadReports(), by ID.

_readErrors: ClassVar[dict[str, Exception]]

Why a report couldn’t be read, by report ID.

_LEGEND: ClassVar[tuple[tuple[str, str], ...]] = (('✅', 'passed'), ('❌', 'failed'), ('⚠️', 'skipped'), ('➖', 'excluded'), ('❗', 'errored'), ('⛔', 'setup error'), ('🚫', 'aborted'), ('❓', 'unknown'))

The status symbols of testsuites and testcases with the word explaining each, in the order of the legend.

_cssClasses: list[str]

Additional CSS classes of the table.

_reportID: str

Identifier of the report in the configuration.

_reportFile: Path

The report file.

_hideTestsuiteSummary: bool

Whether the testsuite summary’s row is left out.

_testsuiteSummaryName: str

Name replacing the testsuite summary’s name, or "".

_showTestcases: ShowTestcases

Which testcases are listed.

_legend: LegendPosition

Where the legend of the status symbols is drawn, by option :legend:.

_testsuite: TestsuiteSummary

The report’s testsuite summary.

_CheckOptions()[source]

Parse all directive options or use default values.

A derived class sets _cssClasses, _reportID, _reportFile, _hideTestsuiteSummary, _testsuiteSummaryName and _showTestcases.

Return type:

None

classmethod CheckConfiguration(sphinxApplication, sphinxConfiguration)[source]

Check the configuration value and load the report configurations.

Parameters:

  • sphinxApplication (Sphinx) – Sphinx application instance.

  • sphinxConfiguration (Config) – Sphinx configuration instance.

Return type:

None

classmethod ReadReports(sphinxApplication)[source]

Read every configured report, once per build.

A report that can’t be read keeps the exception, which a directive or a report’s pages show when they need it.

Parameters:

sphinxApplication (Sphinx) – Sphinx application instance.

Return type:

None

classmethod GetReport(reportID)[source]

Return a report read by ReadReports().

Parameters:

reportID (str) – Identifier of the report.

Return type:

TestsuiteSummary

Returns:

The report’s testsuite summary.

Raises:

ReportExtensionError – If the report wasn’t read, chained to the exception reading it raised.

classmethod _ReadReport(reportFile)[source]

Read a report file.

Parameters:

reportFile (Path) – The report file.

Return type:

TestsuiteSummary

Returns:

The report’s testsuite summary, aggregated.

classmethod _CheckConfiguration(sphinxConfiguration)[source]

Check and load the report configurations from the configuration value _CONFIG_VALUE.

Parameters:

sphinxConfiguration (Config) – Sphinx configuration instance.

Raises:

  • ReportExtensionError – If the configuration value isn’t registered.

  • ReportExtensionError – If a report configuration has no report file (key _REPORT_KEY).

  • ReportExtensionError – If the report file doesn’t exist.

  • ReportExtensionError – If pages isn’t a string.

  • ReportExtensionError – If pages isn’t a relative document name.
    Use a name like ‘unittests/src’, separated by ‘/’, without ‘.’ or ‘..’.

Return type:

None

_Columns()[source]

Return the table’s columns after the first one, which names the rows.

Return type:

list[Column | ColumnGroup]

Returns:

The columns and groups of columns, in their order in the table.

_Pages()[source]

Return the pages of the report, which the first column links to.

Return type:

ReportPages[Any] | None

Returns:

The report’s pages, or None if it has none.

_TableClasses()[source]

Return the CSS classes of the table: report-unittest-table, report-unittest-<report ID> and the classes of option :class:.

Return type:

list[str]

Returns:

The CSS classes.

_SortedValues(d)[source]

Yield the values of a mapping, sorted by key.

Parameters:

d (Mapping[str, Any]) – The mapping, e.g. a testsuite’s testcases by name.

Return type:

Generator[Any]

Returns:

A generator of the values, sorted by their keys.

static _ConvertTestcaseStatusToSymbol(status)[source]

Return the symbol shown for a testcase’s status.

Parameters:

status (TestcaseStatus) – The testcase’s status.

Return type:

str

Returns:

An emoji, e.g. ✅ for a passed testcase.

static _ConvertTestsuiteStatusToSymbol(status)[source]

Return the symbol shown for a testsuite’s status.

Parameters:

status (TestsuiteStatus) – The testsuite’s status.

Return type:

str

Returns:

An emoji, e.g. ✅ for a passed testsuite.

static _FormatTimedelta(delta)[source]

Format a duration as HH:MM:SS.sss, rounded to milliseconds.

Parameters:

delta (timedelta | None) – The duration, or None.

Return type:

str

Returns:

The formatted duration, or "" for None.

_GenerateTestSummaryTable()[source]

Build the table: a header of the columns, a row per testsuite and listed testcase, and a summary row.

A header has a second row, if a column is a ColumnGroup.

Return type:

table

Returns:

The table.

_CreateLegend()[source]

Build the legend of the status symbols: a paragraph naming each symbol of _LEGEND with its word.

The paragraph gets the CSS classes report-unittest-legend and report-unittest-legend-<position>.

Return type:

paragraph

Returns:

The legend.

_RenderRoot(tableBody, columns, testsuiteSummary, includeRoot=True, testsuiteSummaryName=None)[source]

Add the rows of a testsuite summary: optionally its own row, its testsuites’ rows, and the summary row.

Parameters:

  • tableBody (tbody) – The table body the rows are added to.

  • columns (list[Column]) – The columns after the first one.

  • testsuiteSummary (TestsuiteSummary) – The testsuite summary.

  • includeRoot (bool) – Optional, whether the testsuite summary gets a row of its own. Default: True.

  • testsuiteSummaryName (str | None) – Optional, name replacing the testsuite summary’s name; "" keeps it. Default: None.

Return type:

None

_RenderTestsuite(tableBody, columns, testsuite, level)[source]

Add a row for a testsuite, then - recursively - rows for its testsuites and its listed testcases.

Parameters:

  • tableBody (tbody) – The table body the rows are added to.

  • columns (list[Column]) – The columns after the first one.

  • testsuite (Testsuite) – The testsuite.

  • level (int) – The testsuite’s depth in the hierarchy, shown by indentation.

Return type:

None

_RenderTestcase(tableBody, columns, testcase, level)[source]

Add a row for a testcase.

Parameters:

  • tableBody (tbody) – The table body the row is added to.

  • columns (list[Column]) – The columns after the first one.

  • testcase (Testcase) – The testcase.

  • level (int) – The testcase’s depth in the hierarchy, shown by indentation.

Return type:

None

_NameEntry(level, state, entity, roleName)[source]

Create the cell naming a testsuite or testcase, indented, and linked to its page if the report has pages.

Parameters:

  • level (int) – The number of indentation steps.

  • state (str) – The status symbol written before the name.

  • entity (Testsuite | Testcase) – The testsuite or testcase.

  • roleName (str) – The role referring to it: ts for a testsuite, tc for a testcase.

Return type:

entry

Returns:

The table cell.

_RenderSummary(tableBody, columns, testsuiteSummary)[source]

Add the summary row: the overall status and counts.

Parameters:

  • tableBody (tbody) – The table body the row is added to.

  • columns (list[Column]) – The columns after the first one.

  • testsuiteSummary (TestsuiteSummary) – The testsuite summary.

Return type:

None

run()[source]

Read the configured report and return it as a table, on landscape pages in LaTeX.

The legend of the status symbols is drawn below the table, or above it, as option :legend: chooses. :legend: none draws no legend.

A report with pages adds a hidden table of contents of its top-level testsuites, so the pages are below this document in the navigation.

Return type:

list[Node]

Returns:

A Landscape container holding the table and its legend, or the error message; then the table of contents, if the report has pages.

_CreateDoubleRowTableHeader(columns, identifier, classes)

Create a table whose header spans two rows, so a column can group sub-columns.

A column’s subColumns is None when it spans both header rows, and otherwise holds the (title, width) pairs below it.

Parameters:
Return type:

tgroup

Returns:

The table’s column group, with both header rows already in it.

_CreateRotatedTableHeader(columns, identifier, classes)

Create a table whose header titles are rotated, for many narrow columns.

Parameters:

  • columns (list[tuple[str, list[str] | None]]) – One (title, classes) pair per column; the classes are put on the header cell.

  • identifier (str) – Identifier of the table.

  • classes (list[str]) – CSS classes to put on the table.

Return type:

tgroup

Returns:

The table’s column group, with the header row already in it.

_CreateSingleRowTableHeader(columns, identifier, classes)

Create a table with a single header row.

Parameters:

  • columns (list[tuple[str, int | None]]) – One (title, width) pair per column; a width of None leaves it to the writer.

  • identifier (str) – Identifier of the table.

  • classes (list[str]) – CSS classes to put on the table.

Return type:

tgroup

Returns:

The table’s column group, with the header row already in it.

_ParseBooleanOption(optionName, default=None)

Read an option written as yes/true or no/false.

Parameters:

  • optionName (str) – Name of the option to read.

  • default (bool | None) – Optional, the value to return when the option wasn’t given.

Return type:

bool

Returns:

The option’s value.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the option’s value is neither of the two accepted spellings.

_ParseStringOption(optionName, default=None, regexp='\\w+')

Read an option that has to match a regular expression.

The pattern defaults to one or more word characters.

Parameters:

  • optionName (str) – Name of the option to read.

  • default (str | None) – Optional, the value to return when the option wasn’t given.

  • regexp (str) – Optional, the pattern the value has to match.

Return type:

str

Returns:

The option’s value.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the option’s value doesn’t match the pattern.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
Return type:

None

_internalError(container, location, message, exception)

Report an exception a directive couldn’t recover from, in the log and on the page.

A directive that fails silently leaves a hole in the documentation that nobody notices. This puts the message where a reader sees it and the traceback where a maintainer does. The exception’s notes - e.g. how to install a missing package - are logged below it.

Parameters:

  • container (container) – The container the message is put into.

  • location (str) – Name of the logger, which is what the log line is attributed to.

  • message (str) – What went wrong, in one sentence.

  • exception (Exception) – The exception that was caught.

Return type:

list[Node]

Returns:

The container, as the list a directive’s run returns.

_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Return type:

tuple[str, ...]

Parameters:

sig_node (desc_signature)

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Return type:

str

Parameters:

sig_node (desc_signature)

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

Return type:

None

add_target_and_index(name, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Return type:

None

Parameters:

  • name (ObjDescT)

  • sig (str)

  • signode (desc_signature)

after_content()

Called after parsing content.

Used to reset information about the current directive context on the build environment.

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Called before parsing content.

Used to set information about the current directive context on the build environment.

Return type:

None

property config: Config

Reference to the Config object.

Added in version 1.8.

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = False

A boolean; True if the last argument may contain spaces.

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signatures()

Retrieve the signatures to document from the directive arguments.

By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str | None, int | None]

handle_signature(sig, signode)

Parse the signature sig.

The individual nodes are then appended to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

Return type:

str

Parameters:

  • sig (str)

  • signode (desc_signature)

has_content = False

A boolean; True if content is allowed.

option_spec: ClassVar[OptionSpec] = {}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required ones.

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

required_arguments = 0

Number of required directive arguments.

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Return type:

None

Parameters:

node (Node)

transform_content(content_node)

Can be used to manipulate the content.

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed.

Return type:

None

Parameters:

content_node (desc_content)

directiveName: str

Name the directive is invoked by, used in every error message.

class pyTooling.Sphinx.Unittest.UnittestSummary(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

The report:unittest-summary directive: a table of a unit test report, per testsuite and testcase.

Inheritance

Inheritance diagram of UnittestSummary

directiveName: str = 'unittest-summary'

Name the directive is invoked by.

has_content = False

A boolean; True if content is allowed.

required_arguments = 0

Number of required directive arguments.

optional_arguments = 6

Number of optional arguments.

option_spec: dict[str, Any] = {'class': <function strip>, 'hide-testsuite-summary': <function flag>, 'legend': <bound method StringEnum.Parse of <enum 'LegendPosition'>>, 'no-assertions': <function flag>, 'reportid': <function stripAndNormalize>, 'show-testcases': <function stripAndNormalize>, 'testsuite-summary-name': <function strip>}

Mapping of option names to validator functions.

configValues: ClassVar[dict[str, tuple[Any, str, Any]]] = {'Testsuites': ({}, 'env', <class 'dict'>)}

Values added to conf.py, as name: (default, rebuild, types), prefixed by CONFIG_PREFIX.

_CONFIG_VALUE: ClassVar[str] = 'pyTooling_Unittest_Testsuites'

Configuration value declaring the reports.

_REPORT_KEY: ClassVar[str] = 'xml_report'

Key of a report’s file in its configuration.

_REPORT_KIND: ClassVar[str] = 'Unittest report'

The kind of report, as a message names it.

classmethod CheckConfiguration(sphinxApplication, sphinxConfiguration)

Check the configuration value and load the report configurations.

Parameters:

  • sphinxApplication (Sphinx) – Sphinx application instance.

  • sphinxConfiguration (Config) – Sphinx configuration instance.

Return type:

None

classmethod GetReport(reportID)

Return a report read by ReadReports().

Parameters:

reportID (str) – Identifier of the report.

Return type:

TestsuiteSummary

Returns:

The report’s testsuite summary.

Raises:

ReportExtensionError – If the report wasn’t read, chained to the exception reading it raised.

classmethod ReadReports(sphinxApplication)

Read every configured report, once per build.

A report that can’t be read keeps the exception, which a directive or a report’s pages show when they need it.

Parameters:

sphinxApplication (Sphinx) – Sphinx application instance.

Return type:

None

classmethod _CheckConfiguration(sphinxConfiguration)

Check and load the report configurations from the configuration value _CONFIG_VALUE.

Parameters:

sphinxConfiguration (Config) – Sphinx configuration instance.

Raises:

  • ReportExtensionError – If the configuration value isn’t registered.

  • ReportExtensionError – If a report configuration has no report file (key _REPORT_KEY).

  • ReportExtensionError – If the report file doesn’t exist.

  • ReportExtensionError – If pages isn’t a string.

  • ReportExtensionError – If pages isn’t a relative document name.
    Use a name like ‘unittests/src’, separated by ‘/’, without ‘.’ or ‘..’.

Return type:

None

static _ConvertTestcaseStatusToSymbol(status)

Return the symbol shown for a testcase’s status.

Parameters:

status (TestcaseStatus) – The testcase’s status.

Return type:

str

Returns:

An emoji, e.g. ✅ for a passed testcase.

static _ConvertTestsuiteStatusToSymbol(status)

Return the symbol shown for a testsuite’s status.

Parameters:

status (TestsuiteStatus) – The testsuite’s status.

Return type:

str

Returns:

An emoji, e.g. ✅ for a passed testsuite.

_CreateDoubleRowTableHeader(columns, identifier, classes)

Create a table whose header spans two rows, so a column can group sub-columns.

A column’s subColumns is None when it spans both header rows, and otherwise holds the (title, width) pairs below it.

Parameters:
Return type:

tgroup

Returns:

The table’s column group, with both header rows already in it.

_CreateLegend()

Build the legend of the status symbols: a paragraph naming each symbol of _LEGEND with its word.

The paragraph gets the CSS classes report-unittest-legend and report-unittest-legend-<position>.

Return type:

paragraph

Returns:

The legend.

_CreateRotatedTableHeader(columns, identifier, classes)

Create a table whose header titles are rotated, for many narrow columns.

Parameters:

  • columns (list[tuple[str, list[str] | None]]) – One (title, classes) pair per column; the classes are put on the header cell.

  • identifier (str) – Identifier of the table.

  • classes (list[str]) – CSS classes to put on the table.

Return type:

tgroup

Returns:

The table’s column group, with the header row already in it.

_CreateSingleRowTableHeader(columns, identifier, classes)

Create a table with a single header row.

Parameters:

  • columns (list[tuple[str, int | None]]) – One (title, width) pair per column; a width of None leaves it to the writer.

  • identifier (str) – Identifier of the table.

  • classes (list[str]) – CSS classes to put on the table.

Return type:

tgroup

Returns:

The table’s column group, with the header row already in it.

static _FormatTimedelta(delta)

Format a duration as HH:MM:SS.sss, rounded to milliseconds.

Parameters:

delta (timedelta | None) – The duration, or None.

Return type:

str

Returns:

The formatted duration, or "" for None.

_GenerateTestSummaryTable()

Build the table: a header of the columns, a row per testsuite and listed testcase, and a summary row.

A header has a second row, if a column is a ColumnGroup.

Return type:

table

Returns:

The table.

_LEGEND: ClassVar[tuple[tuple[str, str], ...]] = (('✅', 'passed'), ('❌', 'failed'), ('⚠️', 'skipped'), ('➖', 'excluded'), ('❗', 'errored'), ('⛔', 'setup error'), ('🚫', 'aborted'), ('❓', 'unknown'))

The status symbols of testsuites and testcases with the word explaining each, in the order of the legend.

_NAME_COLUMN: ClassVar[Column] = <pyTooling.Sphinx.Unittest.Column object>

The first column, naming the rows.

_NameEntry(level, state, entity, roleName)

Create the cell naming a testsuite or testcase, indented, and linked to its page if the report has pages.

Parameters:

  • level (int) – The number of indentation steps.

  • state (str) – The status symbol written before the name.

  • entity (Testsuite | Testcase) – The testsuite or testcase.

  • roleName (str) – The role referring to it: ts for a testsuite, tc for a testcase.

Return type:

entry

Returns:

The table cell.

_ParseBooleanOption(optionName, default=None)

Read an option written as yes/true or no/false.

Parameters:

  • optionName (str) – Name of the option to read.

  • default (bool | None) – Optional, the value to return when the option wasn’t given.

Return type:

bool

Returns:

The option’s value.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the option’s value is neither of the two accepted spellings.

_ParseStringOption(optionName, default=None, regexp='\\w+')

Read an option that has to match a regular expression.

The pattern defaults to one or more word characters.

Parameters:

  • optionName (str) – Name of the option to read.

  • default (str | None) – Optional, the value to return when the option wasn’t given.

  • regexp (str) – Optional, the pattern the value has to match.

Return type:

str

Returns:

The option’s value.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the option’s value doesn’t match the pattern.

_RenderRoot(tableBody, columns, testsuiteSummary, includeRoot=True, testsuiteSummaryName=None)

Add the rows of a testsuite summary: optionally its own row, its testsuites’ rows, and the summary row.

Parameters:

  • tableBody (tbody) – The table body the rows are added to.

  • columns (list[Column]) – The columns after the first one.

  • testsuiteSummary (TestsuiteSummary) – The testsuite summary.

  • includeRoot (bool) – Optional, whether the testsuite summary gets a row of its own. Default: True.

  • testsuiteSummaryName (str | None) – Optional, name replacing the testsuite summary’s name; "" keeps it. Default: None.

Return type:

None

_RenderSummary(tableBody, columns, testsuiteSummary)

Add the summary row: the overall status and counts.

Parameters:

  • tableBody (tbody) – The table body the row is added to.

  • columns (list[Column]) – The columns after the first one.

  • testsuiteSummary (TestsuiteSummary) – The testsuite summary.

Return type:

None

_RenderTestcase(tableBody, columns, testcase, level)

Add a row for a testcase.

Parameters:

  • tableBody (tbody) – The table body the row is added to.

  • columns (list[Column]) – The columns after the first one.

  • testcase (Testcase) – The testcase.

  • level (int) – The testcase’s depth in the hierarchy, shown by indentation.

Return type:

None

_RenderTestsuite(tableBody, columns, testsuite, level)

Add a row for a testsuite, then - recursively - rows for its testsuites and its listed testcases.

Parameters:

  • tableBody (tbody) – The table body the rows are added to.

  • columns (list[Column]) – The columns after the first one.

  • testsuite (Testsuite) – The testsuite.

  • level (int) – The testsuite’s depth in the hierarchy, shown by indentation.

Return type:

None

_SortedValues(d)

Yield the values of a mapping, sorted by key.

Parameters:

d (Mapping[str, Any]) – The mapping, e.g. a testsuite’s testcases by name.

Return type:

Generator[Any]

Returns:

A generator of the values, sorted by their keys.

_TableClasses()

Return the CSS classes of the table: report-unittest-table, report-unittest-<report ID> and the classes of option :class:.

Return type:

list[str]

Returns:

The CSS classes.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
Return type:

None

_internalError(container, location, message, exception)

Report an exception a directive couldn’t recover from, in the log and on the page.

A directive that fails silently leaves a hole in the documentation that nobody notices. This puts the message where a reader sees it and the traceback where a maintainer does. The exception’s notes - e.g. how to install a missing package - are logged below it.

Parameters:

  • container (container) – The container the message is put into.

  • location (str) – Name of the logger, which is what the log line is attributed to.

  • message (str) – What went wrong, in one sentence.

  • exception (Exception) – The exception that was caught.

Return type:

list[Node]

Returns:

The container, as the list a directive’s run returns.

_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Return type:

tuple[str, ...]

Parameters:

sig_node (desc_signature)

_testSummaries: ClassVar[dict[str, TestsuiteConfiguration]] = {'example': {'pages': 'unittests/example', 'xml_report': PosixPath('../tests/data/Report/unittest.xml')}, 'pytooling': {'pages': 'unittests/pytooling', 'xml_report': PosixPath('../tests/data/Report/TestReport.xml')}, 'src': {'pages': 'unittests/src', 'xml_report': PosixPath('../report/unit/unittest.xml')}}

Report configurations, by report ID.

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Return type:

str

Parameters:

sig_node (desc_signature)

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

Return type:

None

add_target_and_index(name, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Return type:

None

Parameters:

  • name (ObjDescT)

  • sig (str)

  • signode (desc_signature)

after_content()

Called after parsing content.

Used to reset information about the current directive context on the build environment.

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Called before parsing content.

Used to set information about the current directive context on the build environment.

Return type:

None

property config: Config

Reference to the Config object.

Added in version 1.8.

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = False

A boolean; True if the last argument may contain spaces.

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signatures()

Retrieve the signatures to document from the directive arguments.

By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str | None, int | None]

handle_signature(sig, signode)

Parse the signature sig.

The individual nodes are then appended to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

Return type:

str

Parameters:

  • sig (str)

  • signode (desc_signature)

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Read the configured report and return it as a table, on landscape pages in LaTeX.

The legend of the status symbols is drawn below the table, or above it, as option :legend: chooses. :legend: none draws no legend.

A report with pages adds a hidden table of contents of its top-level testsuites, so the pages are below this document in the navigation.

Return type:

list[Node]

Returns:

A Landscape container holding the table and its legend, or the error message; then the table of contents, if the report has pages.

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Return type:

None

Parameters:

node (Node)

transform_content(content_node)

Can be used to manipulate the content.

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed.

Return type:

None

Parameters:

content_node (desc_content)

_cssClasses: list[str]

Additional CSS classes of the table.

_reportID: str

Identifier of the report in the configuration.

_reportFile: Path

The report file.

_hideTestsuiteSummary: bool

Whether the testsuite summary’s row is left out.

_testsuiteSummaryName: str

Name replacing the testsuite summary’s name, or "".

_showTestcases: ShowTestcases

Which testcases are listed.

_legend: LegendPosition

Where the legend of the status symbols is drawn, by option :legend:.

_testsuite: TestsuiteSummary

The report’s testsuite summary.

_reports: ClassVar[dict[str, TestsuiteSummary]] = {'example': <pyEDAA.Reports.Unittesting.TestsuiteSummary object>, 'pytooling': <pyEDAA.Reports.Unittesting.pyTooling.Document object>, 'src': <pyEDAA.Reports.Unittesting.TestsuiteSummary object>}

Reports read by ReadReports(), by ID.

_readErrors: ClassVar[dict[str, Exception]] = {}

Why a report couldn’t be read, by report ID.

_noAssertions: bool

Whether the assertion column is left out.

_CheckOptions()[source]

Parse all directive options or use default values.

Raises:

  • SphinxExtensionError – If option :class: isn’t a list of CSS class names.

  • SphinxExtensionError – If option :show-testcases: is neither all nor not-passed.

  • SphinxExtensionError – If option :reportid: is missing.

  • ReportExtensionError – If pyTooling_Unittest_Testsuites has no entry for the report ID.

Return type:

None

_Columns()[source]

Return the columns after the first one: the counts of testcases, skipped, errored, failed and passed ones, the assertions - unless option :no-assertions: is given -, and the runtime.

Return type:

list[Column | ColumnGroup]

Returns:

The columns.

_Pages()[source]

Return the pages of the report, if it was declared with the key pages.

Return type:

ReportPages[Any] | None

Returns:

The report’s pages, or None if it has none.

classmethod _ReadReport(xmlReport)[source]

Read a report file, choosing the reader by the file’s root element.

Parameters:

xmlReport (Path) – The report file.

Return type:

TestsuiteSummary

Returns:

The report’s testsuite summary, aggregated.

Raises:

  • ReportExtensionError – If the file’s root element is no known report format.

  • ReportsPackageMissingError – If pyEDAA.Reports, or its reader for the report’s format, isn’t installed.