ReportWriter

Summary

Package:

Testing

Doc-string:

documented

File	Expected	Covered	Uncovered	Coverage
ReportWriter.py	22	22	0	100.0%

Source

pyTooling/Testing/ReportWriter.pydocumentedundocumentedignoredexcludednot counted

"""
A pytest plugin writing a test report in :ref:`pyTooling's own format <TESTING/ReportFormat>`.

JUnit XML cannot express two things a marked test suite has: test suites **nest**, where JUnit flattens them into a
dotted ``classname``; and every item carries **four names** - an identifier, a title, a summary and a description -
where JUnit has one name and a bag of flat ``<property>`` pairs.

This writer is opt-in through ``--pytooling-xml=PATH`` and runs happily alongside ``--junit-xml``, so a pipeline
keeps the format its dashboard understands while the richer file is produced from the same reports.

The format's version is the version of its schema - :file:`TestReport-v0.1.xsd` today - so a later version is added
beside it and a reader knows from ``xsi:noNamespaceSchemaLocation`` which one it is holding.

.. todo:: TESTING::ReportWriter Name the generator in a ``<Generator>`` element

   The tool that wrote a report is not part of the format's version, so it is no longer an attribute on the root
   element. Where it belongs is an element of its own at root level, carrying the tool's name and version and
   whatever further meta information a tool wants to add.

.. todo:: TESTING::ReportWriter Add a ``<TestRun>`` level between the report and its test suites

   A run happens on one machine, in one environment, at one time - so a report can hold several of them, and the
   things that describe a run belong to the run rather than to the report:

   .. code-block:: text

      <TestReport>
        <TestRun timestamp="..." duration="...">
          <Environment>
            <Hostname>...</Hostname>
            <OperatingSystem>...</OperatingSystem>
          </Environment>
          <Summary>...</Summary>
          <Description>...</Description>
          <Testsuite ... />
        </TestRun>
      </TestReport>

   The environment is optional, which is what makes a hostname acceptable there: it is written when whoever
   generates the report decides it belongs in it, not by default.

.. hint::

   See :ref:`high-level help <TESTING/ReportFormat>` for the schema and an example.
"""
...

__all__ = ["SCHEMA_VERSION_LATEST", "SCHEMA_FILES", "REPORT_WRITER_KEY"]

SCHEMA_VERSION_LATEST: SemanticVersion = SemanticVersion(0, 1)
"""Latest version of the report format, and the one this writer produces."""

SCHEMA_FILES: dict[SemanticVersion, Path] = {
	SemanticVersion(0, 1): Path("TestReport-v0.1.xsd"),
}
"""Schema file per format version, so a later version is added beside the one in use, not instead of it."""

REPORT_WRITER_KEY: StashKey["TestReportWriter"] = StashKey()
"""Where the writer is stashed on the configuration."""

class _Result(TypedDict, total=False):
	"""What is collected per testcase, assembled from the reports of its phases."""

	nodeID:               str    #: Node ID of the testcase, whose parts name the test suite levels.
	duration:             float  #: Sum of the durations of the testcase's phases.
	message:              str    #: Text of the failure, or an empty string.
	status:               str    #: ``passed``, ``failed``, ``errored`` or ``skipped``.
	title:                str    #: Title of the testcase, if it is marked.
	summary:              str    #: Summary of the testcase, if its doc-string has one.
	description:          str    #: Description of the testcase, if its doc-string has one.

@export
class TestReportWriter(metaclass=ExtendedType, slots=True):
	"""
	Collects the reports of a session and writes them as one nested XML document.

	The nesting comes from the dotted ``classname`` pytest reports: ``tests.unit.Versioning`` becomes three levels
	of ``<Testsuite>``, so a reader sees the hierarchy the test suite actually has.
	"""

	_path:      Path                          #: Where the report is written.
	_results:   dict[str, _Result]            #: Collected results, keyed by node ID.
	_hierarchy: dict[str, dict[str, str]]     #: Names of every test suite level, keyed by its dotted path.

	def __init__(self, path: Path, hierarchy: Nullable[dict[str, dict[str, str]]] = None) -> None:
		"""
		Initializes the writer with the path it writes to.

		:param path:      Path of the report file to write.
		:param hierarchy: Optional, the names of every test suite level, keyed by its dotted path, as
		                  :mod:`pyTooling.Testing.PyTest` collects them. Without it - when the marker plugin is not
		                  registered - the test suite elements carry no names.
		"""
		...

	def pytest_runtest_logreport(self, report: Any) -> None:
		"""
		Collect one phase of one testcase.

		:param report: The report of one phase of one testcase.
		"""
		...

	def _testsuiteFor(self, root: Element, suites: dict[str, Element], nodeID: str) -> Element:
		"""
		Return the ``<Testsuite>`` element a testcase belongs into, creating the missing levels on the way.

		:param root:    The report element every path starts at.
		:param suites:  Elements created so far, keyed by their dotted path.
		:param nodeID:  Node ID of the testcase, whose ``::``-separated parts name the levels.
		:returns:       The innermost test suite element.
		"""
		...

	def pytest_sessionfinish(self, session: Session, exitstatus: int) -> None:
		"""
		Write the collected results as one XML document.

		:param session:    The finished session.
		:param exitstatus: The exit status the session ended with.
		"""
		...

@export
def pytest_addoption(parser: Parser) -> None:
	"""
	Add the ``--pytooling-xml`` option selecting the report's path.

	:param parser: The command line parser to add the option to.
	"""
	...

@export
def pytest_configure(config: Config) -> None:
	"""
	Register the writer, if a path was given.

	:param config: The session's configuration.
	"""
	...