# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2026-2026 Electronic Design Automation Abstraction (EDA²) #
# #
# Licensed under the Apache License, Version 2.0 (the "License"); #
# you may not use this file except in compliance with the License. #
# You may obtain a copy of the License at #
# #
# http://www.apache.org/licenses/LICENSE-2.0 #
# #
# Unless required by applicable law or agreed to in writing, software #
# distributed under the License is distributed on an "AS IS" BASIS, #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
# See the License for the specific language governing permissions and #
# limitations under the License. #
# #
# SPDX-License-Identifier: Apache-2.0 #
# ==================================================================================================================== #
#
"""
Reader and writer for JUnit XML files written by go-junit-report.
`go-junit-report <https://github.com/jstemmer/go-junit-report>`__ converts the output of ``go test`` into JUnit XML. A
test suite is a Go package named by its import path, a test case is a test, a subtest or an example.
"""
from __future__ import annotations
from datetime import timedelta
from pathlib import Path
from re import fullmatch
from typing import Optional as Nullable, Type, ClassVar
from lxml.etree import ElementTree, Element, SubElement, tostring, _Element
from pyTooling.Decorators import export, InheritDocString, DocStringMergeStrategy
from pyTooling.Stopwatch import Stopwatch
from pyEDAA.Reports.Unittesting import UnittestError, TestsuiteKind, TestsuiteSummary as ut_TestsuiteSummary, \
Testsuite as ut_Testsuite
from pyEDAA.Reports.Unittesting.JUnit import Testcase as ju_Testcase, Testclass as ju_Testclass, \
Testsuite as ju_Testsuite, TestsuiteSummary as ju_TestsuiteSummary, \
Document as ju_Document
[docs]
@export
@InheritDocString(ju_Testcase, DocStringMergeStrategy.BaseLast)
class Testcase(ju_Testcase):
"""
This is a derived implementation for the go-junit-report JUnit dialect.
"""
[docs]
@export
@InheritDocString(ju_Testclass, DocStringMergeStrategy.BaseLast)
class Testclass(ju_Testclass):
"""
This is a derived implementation for the go-junit-report JUnit dialect.
"""
[docs]
@export
@InheritDocString(ju_Testsuite, DocStringMergeStrategy.BaseLast)
class Testsuite(ju_Testsuite):
"""
This is a derived implementation for the go-junit-report JUnit dialect.
"""
[docs]
@classmethod
def FromTestsuite(cls, testsuite: ut_Testsuite) -> Testsuite:
"""
Convert a test suite of the unified test entity data model to the JUnit specific data model's test suite object
adhering to the go-junit-report JUnit dialect.
:param testsuite: Test suite from unified data model.
:returns: Test suite from JUnit specific data model (go-junit-report JUnit dialect).
:raises UnittestError: If a test case of the test suite isn't part of a hierarchy.
"""
juTestsuite = cls(
testsuite._name,
hostname=testsuite._hostname,
startTime=testsuite._startTime,
duration=testsuite._totalDuration,
status=testsuite._status,
)
for tc in testsuite.IterateTestcases():
ts = tc._parent
if ts is None:
raise UnittestError(f"Testcase '{tc._name}' is not part of a hierarchy.")
elif ts is testsuite:
juTestsuite.AddTestcase(Testcase.FromTestcase(tc))
continue
classname = ts._name
ts = ts._parent
while ts is not None and ts._kind > TestsuiteKind.Logical:
classname = f"{ts._name}.{classname}"
ts = ts._parent
if classname in juTestsuite._testclasses:
juClass = juTestsuite._testclasses[classname]
else:
juClass = Testclass(classname, parent=juTestsuite)
juClass.AddTestcase(Testcase.FromTestcase(tc))
return juTestsuite
[docs]
def ToTestsuite(self) -> ut_Testsuite:
"""
Convert this test suite to a test suite of the unified test entity data model.
Each test class becomes a child test suite of kind :attr:`~pyEDAA.Reports.Unittesting.TestsuiteKind.Class`, named
by the whole class name. A class name is a Go import path like ``github.com/user/module/package``, so it isn't
split at ``.`` into packages.
:returns: A test suite of the unified test entity data model.
"""
return ut_Testsuite(
self._name,
kind=TestsuiteKind.Logical,
hostname=self._hostname,
startTime=self._startTime,
totalDuration=self._duration,
status=self._status,
testsuites=(testclass.ToTestsuite() for testclass in self._testclasses.values()),
testcases=(tc.ToTestcase() for tc in self._testcases.values())
)
[docs]
@export
@InheritDocString(ju_TestsuiteSummary, DocStringMergeStrategy.BaseLast)
class TestsuiteSummary(ju_TestsuiteSummary):
"""
This is a derived implementation for the go-junit-report JUnit dialect.
"""
[docs]
@classmethod
def FromTestsuiteSummary(cls, testsuiteSummary: ut_TestsuiteSummary) -> TestsuiteSummary:
"""
Convert a test suite summary of the unified test entity data model to the JUnit specific data model's test suite
summary object adhering to the go-junit-report JUnit dialect.
:param testsuiteSummary: Test suite summary from unified data model.
:returns: Test suite summary from JUnit specific data model (go-junit-report JUnit dialect).
"""
return cls(
testsuiteSummary._name,
startTime=testsuiteSummary._startTime,
duration=testsuiteSummary._totalDuration,
status=testsuiteSummary._status,
testsuites=(Testsuite.FromTestsuite(testsuite) for testsuite in testsuiteSummary._testsuites.values())
)
[docs]
@export
class Document(ju_Document):
"""
A document reader and writer for the go-junit-report JUnit XML file format.
This class reads, validates and transforms an XML file in the go-junit-report JUnit format into a JUnit data model. It
can then be converted into a unified test entity data model.
In reverse, a JUnit data model instance with the specific go-junit-report JUnit file format can be created from a
unified test entity data model. This data model can be written as XML into a file.
"""
_DIALECT: ClassVar[str] = "go-junit-report" #: Name of the dialect.
_TESTCASE: ClassVar[Type[Testcase]] = Testcase #: Test case class of the dialect.
_TESTCLASS: ClassVar[Type[Testclass]] = Testclass #: Test class class of the dialect.
_TESTSUITE: ClassVar[Type[Testsuite]] = Testsuite #: Test suite class of the dialect.
[docs]
def Analyze(self) -> None:
"""
Analyze the XML file, parse the content into an XML data structure and validate the data structure using an XML
schema.
.. hint::
The time spend for analysis will be made available via property :data:`AnalysisDuration`.
The used XML schema definition is specific to the go-junit-report JUnit dialect.
"""
xmlSchemaFile = "GoJUnitReport-JUnit.xsd"
self._Analyze(xmlSchemaFile)
[docs]
def Write(self, path: Nullable[Path] = None, overwrite: bool = False, regenerate: bool = False) -> None:
"""
Write the data model as XML into a file adhering to the go-junit-report dialect.
:param path: Optional, path to the XML file, if internal path shouldn't be used.
:param overwrite: Optional, if true, overwrite an existing file.
:param regenerate: Optional, if true, regenerate the XML structure from data model.
:raises UnittestError: If the file cannot be overwritten.
:raises UnittestError: If the internal XML data structure wasn't generated. |br|
Call ``Document.Generate()`` or ``Document.Write(..., regenerate=True)``.
:raises UnittestError: If the file cannot be opened or written.
"""
if path is None:
path = self._path
if not overwrite and path.exists():
raise UnittestError(f"JUnit XML file '{path}' can not be overwritten.") \
from FileExistsError(f"File '{path}' already exists.")
if regenerate:
self.Generate(overwrite=True)
if self._xmlDocument is None:
ex = UnittestError("Internal XML document tree is empty and needs to be generated before write is possible.")
ex.add_note("Call 'Document.Generate()' or 'Document.Write(..., regenerate=True)'.")
raise ex
content = tostring(self._xmlDocument, encoding="utf-8", xml_declaration=True, pretty_print=True)
try:
with path.open("wb") as file:
file.write(content)
except OSError as ex:
raise UnittestError(f"JUnit XML file '{path}' can not be written.") from ex
[docs]
def Convert(self) -> None:
"""
Convert the parsed and validated XML data structure into a JUnit test entity hierarchy.
This method converts the root element.
.. hint::
The time spend for model conversion will be made available via property :data:`ModelConversionDuration`.
:raises UnittestError: If XML was not read and parsed before. |br|
Call ``Document.Analyze()`` or create the document using
``Document(path, analyzeAndConvert=True)``.
"""
if self._xmlDocument is None:
ex = UnittestError(f"JUnit XML file '{self._path}' needs to be read and analyzed by an XML parser.")
ex.add_note("Call 'Document.Analyze()' or create the document using 'Document(path, analyzeAndConvert=True)'.")
raise ex
with Stopwatch() as sw:
rootElement: _Element = self._xmlDocument.getroot()
self._name = self._ConvertName(rootElement, optional=True)
self._duration = self._ConvertTime(rootElement, optional=True)
for rootNode in rootElement.iterchildren(tag="testsuite"): # type: _Element
self._ConvertTestsuite(self, rootNode)
self.Aggregate()
self._modelConversion = sw.Duration
[docs]
def _ConvertTestsuite(self, parent: TestsuiteSummary, testsuitesNode: _Element) -> None:
"""
Convert the XML data structure of a ``<testsuite>`` to a test suite.
A ``<testsuite>`` whose ``<system-out>`` is ``go test``'s result line of a package without tests
(``<tab><import path><tab><tab>coverage: ...``) is named by that import path. go-junit-report names such a package
by its option ``-package-name``, which is empty by default.
This method uses private helper methods provided by the base-class.
:param parent: The test suite summary as a parent element in the test entity hierarchy.
:param testsuitesNode: The current XML element node representing a test suite.
:raises UnittestError: If the test suite has an empty name and no result line naming the package.
"""
name = self._ConvertName(testsuitesNode, optional=False)
if (systemOutNode := testsuitesNode.find("system-out")) is not None and systemOutNode.text is not None:
if (match := fullmatch(r"\t(?P<importPath>\S+)\t\tcoverage: .+", systemOutNode.text)) is not None:
name = match["importPath"]
if name == "":
ex = UnittestError(f"Test suite with id '{testsuitesNode.attrib['id']}' has an empty name.")
ex.add_note("go-junit-report names a package by option '-package-name', if it found no result line for it.")
raise ex
newTestsuite = self._TESTSUITE(
name,
self._ConvertHostname(testsuitesNode, default=None, optional=True),
self._ConvertTimestamp(testsuitesNode, optional=True),
self._ConvertTime(testsuitesNode, optional=False),
parent=parent
)
self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite)
[docs]
def Generate(self, overwrite: bool = False) -> None:
"""
Generate the internal XML data structure from test suites and test cases.
This method generates the XML root element (``<testsuites>``) and recursively calls other generated methods.
:param overwrite: Optional, overwrite the internal XML data structure.
:raises UnittestError: If overwrite is false and the internal XML data structure is not empty.
"""
if not overwrite and self._xmlDocument is not None:
raise UnittestError("Internal XML document is populated with data.")
rootElement = Element("testsuites")
rootElement.attrib["name"] = self._name
if self._duration is not None:
rootElement.attrib["time"] = f"{self._duration.total_seconds():.6f}"
rootElement.attrib["tests"] = str(self._tests)
rootElement.attrib["errors"] = str(self._errored)
rootElement.attrib["failures"] = str(self._failed)
rootElement.attrib["skipped"] = str(self._skipped)
self._xmlDocument = ElementTree(rootElement)
for testsuite in self._testsuites.values():
self._GenerateTestsuite(testsuite, rootElement)
[docs]
def _GenerateTestsuite(self, testsuite: Testsuite, parentElement: _Element) -> None:
"""
Generate the internal XML data structure for a test suite.
This method generates the XML element (``<testsuite>``) and recursively calls other generated methods.
The ``id`` is the test suite's index in the document. Like go-junit-report, a test suite without a duration gets the
sum of its test cases' durations as ``time``.
:param testsuite: The test suite to convert to an XML data structures.
:param parentElement: The parent XML data structure element, this data structure part will be added to.
"""
testsuiteId = len(parentElement)
testsuiteElement = SubElement(parentElement, "testsuite")
testsuiteElement.attrib["name"] = testsuite._name
testsuiteElement.attrib["tests"] = str(testsuite._tests)
testsuiteElement.attrib["failures"] = str(testsuite._failed)
testsuiteElement.attrib["errors"] = str(testsuite._errored)
testsuiteElement.attrib["id"] = str(testsuiteId)
if testsuite._hostname is not None:
testsuiteElement.attrib["hostname"] = testsuite._hostname
testsuiteElement.attrib["skipped"] = str(testsuite._skipped)
if testsuite._duration is not None:
duration = testsuite._duration
else:
duration = sum(
(
testcase._duration
for testcases in (
testsuite._testcases,
*(testclass._testcases for testclass in testsuite._testclasses.values())
)
for testcase in testcases.values()
if testcase._duration is not None
),
timedelta()
)
testsuiteElement.attrib["time"] = f"{duration.total_seconds():.6f}"
if testsuite._startTime is not None:
testsuiteElement.attrib["timestamp"] = f"{testsuite._startTime.isoformat()}"
for tc in testsuite._testcases.values():
self._GenerateTestcase(tc, testsuiteElement)
for testclass in testsuite._testclasses.values():
for tc in testclass._testcases.values():
self._GenerateTestcase(tc, testsuiteElement)
[docs]
def _GenerateTestcase(self, testcase: Testcase, parentElement: _Element) -> None:
"""
Generate the internal XML data structure for a test case.
This method generates the XML element (``<testcase>``) and recursively calls other generated methods.
:param testcase: The test case to convert to an XML data structures.
:param parentElement: The parent XML data structure element, this data structure part will be added to.
"""
testcaseElement = SubElement(parentElement, "testcase")
testcaseElement.attrib["name"] = testcase._name
testcaseElement.attrib["classname"] = testcase.Classname
if testcase._duration is not None:
testcaseElement.attrib["time"] = f"{testcase._duration.total_seconds():.6f}"
self._GenerateTestcaseChildren(testcase, testcaseElement)
[docs]
def _GenerateTestcaseChildren(self, testcase: Testcase, testcaseElement: _Element) -> None:
"""
Generate the child elements of a ``<testcase>`` from the test case's status, message, details and captured output.
Like go-junit-report, every ``<skipped>``, ``<error>`` and ``<failure>`` element has a ``message`` attribute; it's
empty for a test case without a message.
:param testcase: The test case to convert to XML child elements.
:param testcaseElement: The ``<testcase>`` element, the child elements will be added to.
"""
super()._GenerateTestcaseChildren(testcase, testcaseElement)
for statusElement in testcaseElement.iterchildren("skipped", "error", "failure"): # type: _Element
if "message" not in statusElement.attrib:
statusElement.attrib["message"] = ""