# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# 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 the JUnit XML report written by Catch2's JUnit reporter.
.. seealso::
:ref:`UNITTEST/SpecificDataModel/JUnit/Dialect/Catch2`
|rarr| Differences of the Catch2 JUnit dialect.
:ref:`SCHEMAS/Catch2-JUnit`
|rarr| XML schema of the Catch2 JUnit dialect.
"""
from __future__ import annotations
from datetime import timezone
from pathlib import Path
from typing import Optional as Nullable, Type, ClassVar
from lxml.etree import ElementTree, Element, SubElement, tostring, _Element
from pyTooling.Common import firstValue
from pyTooling.Decorators import export, InheritDocString, DocStringMergeStrategy
from pyTooling.Stopwatch import Stopwatch
from pyEDAA.Reports.Unittesting import UnittestError, TestsuiteKind, TestcaseStatus, \
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 Catch2 JUnit dialect.
"""
[docs]
@export
@InheritDocString(ju_Testclass, DocStringMergeStrategy.BaseLast)
class Testclass(ju_Testclass):
"""
This is a derived implementation for the Catch2 JUnit dialect.
"""
[docs]
@export
@InheritDocString(ju_Testsuite, DocStringMergeStrategy.BaseLast)
class Testsuite(ju_Testsuite):
"""
This is a derived implementation for the Catch2 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 Catch2 JUnit dialect.
:param testsuite: Test suite from unified data model.
:returns: Test suite from JUnit specific data model (Catch2 JUnit dialect).
:raises UnittestError: If a test case is not part of a test suite hierarchy.
"""
juTestsuite = cls(
testsuite._name,
hostname=testsuite._hostname,
startTime=testsuite._startTime,
duration=testsuite._totalDuration,
status= testsuite._status,
)
juTestsuite._tests = testsuite._tests
juTestsuite._skipped = testsuite._skipped
juTestsuite._errored = testsuite._errored
juTestsuite._failed = testsuite._failed
juTestsuite._passed = testsuite._passed
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]
@export
@InheritDocString(ju_TestsuiteSummary, DocStringMergeStrategy.BaseLast)
class TestsuiteSummary(ju_TestsuiteSummary):
"""
This is a derived implementation for the Catch2 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 Catch2 JUnit dialect.
:param testsuiteSummary: Test suite summary from unified data model.
:returns: Test suite summary from JUnit specific data model (Catch2 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 Catch2 JUnit XML file format.
This class reads, validates and transforms an XML file in the Catch2 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 Catch2 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] = "Catch2 + JUnit" #: Name of the dialect in messages.
_TESTCASE: ClassVar[Type[Testcase]] = Testcase #: Class of test cases read by this dialect.
_TESTCLASS: ClassVar[Type[Testclass]] = Testclass #: Class of test classes read by this dialect.
_TESTSUITE: ClassVar[Type[Testsuite]] = Testsuite #: Class of test suites read by this 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 Catch2 JUnit dialect.
"""
xmlSchemaFile = "Catch2-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 Catch2 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.
: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 'JUnitDocument.Generate()' or 'JUnitDocument.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.
"""
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 'JUnitDocument.Analyze()' or create the document using 'JUnitDocument(path, parse=True)'.")
raise ex
with Stopwatch() as sw:
rootElement: _Element = self._xmlDocument.getroot()
self._name = self._ConvertName(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.
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.
"""
newTestsuite = Testsuite(
self._ConvertName(testsuitesNode, optional=False),
self._ConvertHostname(testsuitesNode, optional=False),
self._ConvertTimestamp(testsuitesNode, optional=False),
self._ConvertTime(testsuitesNode, optional=True),
parent=parent
)
self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite)
[docs]
def _ConvertTestcaseChildren(self, testcaseNode: _Element, newTestcase: Testcase) -> None:
"""
Convert the child elements of a ``<testcase>`` to the test case's status, message, details and captured output.
A test case tagged with ``[!mayfail]`` or ``[!shouldfail]`` failing as expected has a ``<skipped>`` element in front
of its ``<failure>`` or ``<error>`` element. Its status is skipped, its message is the ``<skipped>`` element's
message, its details are the text of the ``<failure>`` or ``<error>`` element.
:param testcaseNode: The current XML element node representing a test case.
:param newTestcase: The test case to update.
:raises UnittestError: If an unknown element is found.
"""
super()._ConvertTestcaseChildren(testcaseNode, newTestcase)
statusNodes = list(testcaseNode.iterchildren("skipped", "failure", "error"))
if len(statusNodes) == 2:
newTestcase._status = TestcaseStatus.Skipped
newTestcase._message = statusNodes[0].attrib.get("message", None)
[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>``) without attributes 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.
:raises UnittestError: If the document has not exactly one test suite.
"""
if not overwrite and self._xmlDocument is not None:
raise UnittestError("Internal XML document is populated with data.")
if self.TestsuiteCount != 1:
ex = UnittestError(f"The {self._DIALECT} format requires exactly one test suite.")
ex.add_note(f"Found {self.TestsuiteCount} test suites.")
raise ex
rootElement = Element("testsuites")
self._xmlDocument = ElementTree(rootElement)
self._GenerateTestsuite(firstValue(self._testsuites), 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
``tests``, ``failures``, ``errors`` and ``skipped`` attributes count test cases, an unrecorded hostname is written
as ``tbd``.
: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.
:raises UnittestError: If the test suite has no start time.
"""
if testsuite._startTime is None:
raise UnittestError(f"The {self._DIALECT} format requires a timestamp on <testsuite>, but the report has none.")
testsuiteElement = SubElement(parentElement, "testsuite")
testsuiteElement.attrib["name"] = testsuite._name
testsuiteElement.attrib["errors"] = str(testsuite._errored)
testsuiteElement.attrib["failures"] = str(testsuite._failed)
testsuiteElement.attrib["skipped"] = str(testsuite._skipped)
testsuiteElement.attrib["tests"] = str(testsuite._tests)
testsuiteElement.attrib["hostname"] = "tbd" if testsuite._hostname is None else testsuite._hostname
if testsuite._duration is not None:
testsuiteElement.attrib["time"] = f"{testsuite._duration.total_seconds():.3f}"
testsuiteElement.attrib["timestamp"] = testsuite._startTime.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
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)
SubElement(testsuiteElement, "system-out")
SubElement(testsuiteElement, "system-err")
[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.
:raises UnittestError: If the test case has no duration.
"""
if testcase._duration is None:
raise UnittestError(f"The {self._DIALECT} format requires a time on <testcase>, but the report has none.")
testcaseElement = SubElement(parentElement, "testcase")
testcaseElement.attrib["classname"] = testcase.Classname
testcaseElement.attrib["name"] = testcase._name
testcaseElement.attrib["time"] = f"{testcase._duration.total_seconds():.3f}"
testcaseElement.attrib["status"] = "run"
self._GenerateTestcaseChildren(testcase, testcaseElement)