# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2024-2026 Electronic Design Automation Abstraction (EDA²) #
# Copyright 2023-2023 Patrick Lehmann - Bötzingen, Germany #
# #
# 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 #
# ==================================================================================================================== #
#
"""
The pyEDAA.Reports.Unittesting.JUnit package implements a hierarchy of test entities for the JUnit unit testing summary
file format (XML format). This test entity hierarchy is not derived from :class:`pyEDAA.Reports.Unittesting`, because it
doesn't match the unified data model. Nonetheless, both data models can be converted to each other. In addition, derived
data models are provided for the many dialects of that XML file format. See the list modules in this package for the
implemented dialects.
The test entity hierarchy consists of test cases, test classes, test suites and a test summary. Test cases are the leaf
elements in the hierarchy and represent an individual test run. Next, test classes group test cases, because the
original Ant + JUnit format groups test cases (Java methods) in a Java class. Next, test suites are used to group
multiple test classes. Finally, the root element is a test summary. When such a summary is stored in a file format like
Ant + JUnit4 XML, a file format specific document is derived from a summary class.
**Data Model**
.. mermaid::
graph TD;
doc[Document]
sum[Summary]
ts1[Testsuite]
ts11[Testsuite]
ts2[Testsuite]
tc111[Testclass]
tc112[Testclass]
tc23[Testclass]
tc1111[Testcase]
tc1112[Testcase]
tc1113[Testcase]
tc1121[Testcase]
tc1122[Testcase]
tc231[Testcase]
tc232[Testcase]
tc233[Testcase]
doc:::root -.-> sum:::summary
sum --> ts1:::suite
sum ---> ts2:::suite
ts1 --> ts11:::suite
ts11 --> tc111:::cls
ts11 --> tc112:::cls
ts2 --> tc23:::cls
tc111 --> tc1111:::case
tc111 --> tc1112:::case
tc111 --> tc1113:::case
tc112 --> tc1121:::case
tc112 --> tc1122:::case
tc23 --> tc231:::case
tc23 --> tc232:::case
tc23 --> tc233:::case
classDef root fill:#4dc3ff
classDef summary fill:#80d4ff
classDef suite fill:#b3e6ff
classDef cls fill:#ff9966
classDef case fill:#eeccff
"""
from __future__ import annotations
from datetime import datetime, timedelta
from enum import Flag
from io import BytesIO
from pathlib import Path
from typing import Optional as Nullable, Iterable, Dict, Any, Generator, Tuple, Union, TypeVar, Type, ClassVar
from lxml.etree import XMLParser, parse, XMLSchema, ElementTree, Element, SubElement, tostring, \
XMLSyntaxError, _ElementTree, _Element, _Comment, XMLSchemaParseError
from pyTooling.Common import getFullyQualifiedName, getTypeName, getResourceFile
from pyTooling.Decorators import export, readonly
from pyTooling.Stopwatch import Stopwatch
from pyTooling.Exceptions import ToolingException
from pyTooling.MetaClasses import ExtendedType, mustoverride, abstractmethod
from pyTooling.Tree import Node
from pyEDAA.Reports import Resources
from pyEDAA.Reports.Unittesting import UnittestError, AlreadyInTestsuiteError, DuplicateTestsuiteError, \
DuplicateTestcaseError, TestcaseStatus, TestsuiteStatus, TestsuiteKind, \
IterationScheme, TestcaseOutputMixin, Document as ut_Document, \
TestsuiteSummary as ut_TestsuiteSummary, Testsuite as ut_Testsuite, \
Testcase as ut_Testcase
[docs]
@export
class JUnitErrorMixin:
"""An error-mixin for JUnit format specific errors."""
[docs]
@export
class UnittestError(UnittestError, JUnitErrorMixin):
pass
[docs]
@export
class AlreadyInTestsuiteError(AlreadyInTestsuiteError, JUnitErrorMixin):
"""
A unit test exception raised if the element is already part of a hierarchy.
This exception is caused by an inconsistent data model. Elements added to the hierarchy should be part of the same
hierarchy should occur only once in the hierarchy.
.. hint::
This is usually caused by a non-None parent reference.
"""
[docs]
@export
class DuplicateTestsuiteError(DuplicateTestsuiteError, JUnitErrorMixin):
"""
A unit test exception raised on duplicate test suites (by name).
This exception is raised, if a child test suite with same name already exist in the test suite.
.. hint::
Test suite names need to be unique per parent element (test suite or test summary).
"""
[docs]
@export
class DuplicateTestcaseError(DuplicateTestcaseError, JUnitErrorMixin):
"""
A unit test exception raised on duplicate test cases (by name).
This exception is raised, if a child test case with same name already exist in the test suite.
.. hint::
Test case names need to be unique per parent element (test suite).
"""
[docs]
@export
class JUnitReaderMode(Flag):
Default = 0 #: Default behavior
DecoupleTestsuiteHierarchyAndTestcaseClassName = 1 #: Undocumented
TestsuiteType = TypeVar("TestsuiteType", bound="Testsuite")
TestcaseAggregateReturnType = Tuple[int, int, int]
TestsuiteAggregateReturnType = Tuple[int, int, int, int, int, int]
[docs]
@export
class Base(metaclass=ExtendedType, slots=True):
"""
Base-class for all test entities (test cases, test classes, test suites, ...).
It provides a reference to the parent test entity, so bidirectional referencing can be used in the test entity
hierarchy.
Every test entity has a name to identity it. It's also used in the parent's child element dictionaries to identify the
child. |br|
E.g. it's used as a test case name in the dictionary of test cases in a test class.
"""
_parent: Nullable[Testsuite]
_name: str
[docs]
def __init__(self, name: str, *, parent: Nullable[Testsuite] = None) -> None:
"""
Initializes the fields of the base-class.
:param name: Name of the test entity.
:param parent: Optional, reference to the parent test entity.
:raises ValueError: When parameter 'name' is None.
:raises TypeError: When parameter 'name' is not a string.
:raises ValueError: When parameter 'name' is empty.
"""
if name is None:
raise ValueError("Parameter 'name' is None.")
elif not isinstance(name, str):
ex = TypeError("Parameter 'name' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
raise ex
elif name.strip() == "":
raise ValueError("Parameter 'name' is empty.")
self._parent = parent
self._name = name
@readonly
def Parent(self) -> Nullable[Testsuite]:
"""
Read-only property to access the reference to the parent test entity.
:returns: Reference to the parent entity.
"""
return self._parent
# QUESTION: allow Parent as setter?
@readonly
def Name(self) -> str:
"""
Read-only property to access the test entity's name.
:returns: Name of the test entity.
"""
return self._name
[docs]
@export
class BaseWithProperties(Base):
"""
Base-class for all test entities supporting properties (test cases, test suites, ...).
Every test entity has fields for the test duration and number of executed assertions.
Every test entity offers an internal dictionary for properties.
"""
_duration: Nullable[timedelta]
_assertionCount: Nullable[int]
_properties: Dict[str, Any]
[docs]
def __init__(
self,
name: str,
duration: Nullable[timedelta] = None,
assertionCount: Nullable[int] = None,
*,
parent: Nullable[Testsuite] = None
) -> None:
"""
Initializes the fields of the base-class.
:param name: Name of the test entity.
:param duration: Optional, duration of the entity's execution.
:param assertionCount: Optional, number of assertions within the test.
:param parent: Optional, reference to the parent test entity.
:raises TypeError: If parameter 'duration' is not a timedelta.
:raises TypeError: If parameter 'assertionCount' is not an integer.
"""
super().__init__(name, parent=parent)
if duration is not None and not isinstance(duration, timedelta):
ex = TypeError("Parameter 'duration' is not of type 'timedelta'.")
ex.add_note(f"Got type '{getFullyQualifiedName(duration)}'.")
raise ex
if assertionCount is not None and not isinstance(assertionCount, int):
ex = TypeError("Parameter 'assertionCount' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(assertionCount)}'.")
raise ex
self._duration = duration
self._assertionCount = assertionCount
self._properties = {}
@readonly
def Duration(self) -> timedelta:
"""
Read-only property to access the duration of a test entity run.
.. note::
The JUnit format doesn't distinguish setup, run and teardown durations.
:returns: Duration of the entity's execution.
"""
return self._duration
@readonly
@abstractmethod
def AssertionCount(self) -> int:
"""
Read-only property to access the number of assertions (checks) in a test case.
.. note::
The JUnit format doesn't distinguish passed and failed assertions.
:returns: Number of assertions.
"""
[docs]
def __len__(self) -> int:
"""
Returns the number of annotated properties.
Syntax: :pycode:`length = len(obj)`
:returns: Number of annotated properties.
"""
return len(self._properties)
[docs]
def __getitem__(self, name: str) -> Any:
"""
Access a property by name.
Syntax: :pycode:`value = obj[name]`
:param name: Name if the property.
:returns: Value of the accessed property.
"""
return self._properties[name]
[docs]
def __setitem__(self, name: str, value: Any) -> None:
"""
Set the value of a property by name.
If the property doesn't exist yet, it's created.
Syntax: :pycode:`obj[name] = value`
:param name: Name of the property.
:param value: Value of the property.
"""
self._properties[name] = value
[docs]
def __delitem__(self, name: str) -> None:
"""
Delete a property by name.
Syntax: :pycode:`del obj[name]`
:param name: Name if the property.
"""
del self._properties[name]
[docs]
def __contains__(self, name: str) -> bool:
"""
Returns True, if a property was annotated by this name.
Syntax: :pycode:`name in obj`
:param name: Name of the property.
:returns: True, if the property was annotated.
"""
return name in self._properties
[docs]
def __iter__(self) -> Generator[Tuple[str, Any], None, None]:
"""
Iterate all annotated properties.
Syntax: :pycode:`for name, value in obj:`
:returns: A generator of property tuples (name, value).
"""
yield from self._properties.items()
[docs]
@export
class Testcase(BaseWithProperties, TestcaseOutputMixin):
"""
A testcase is the leaf-entity in the test entity hierarchy representing an individual test run.
Test cases are grouped by test classes in the test entity hierarchy. These are again grouped by test suites. The root
of the hierarchy is a test summary. A test case without a class (empty ``classname``) belongs to its test suite
directly, e.g. pytest's entry for a skipped test module.
Every test case has an overall status like unknown, skipped, failed or passed. The message and details of a
``<failure>``, ``<error>`` or ``<skipped>`` element, as well as the captured output of ``<system-out>`` and
``<system-err>`` are provided by :class:`~pyEDAA.Reports.Unittesting.TestcaseOutputMixin`.
"""
_status: TestcaseStatus
[docs]
def __init__(
self,
name: str,
duration: Nullable[timedelta] = None,
status: TestcaseStatus = TestcaseStatus.Unknown,
assertionCount: Nullable[int] = None,
message: Nullable[str] = None,
details: Nullable[str] = None,
standardOutput: Nullable[str] = None,
standardError: Nullable[str] = None,
*,
parent: Nullable[Testclass | Testsuite] = None
) -> None:
"""
Initializes the fields of a test case.
:param name: Name of the test entity.
:param duration: Optional, duration of the entity's execution.
:param status: Optional, status of the test case.
:param assertionCount: Optional, number of assertions within the test.
:param message: Optional, message explaining the test case's status.
:param details: Optional, details explaining the test case's status (e.g. a traceback).
:param standardOutput: Optional, captured standard output of the test case.
:param standardError: Optional, captured standard error of the test case.
:param parent: Optional, reference to the parent test class or test suite.
:raises ValueError: If parameter 'assertionCount' is not consistent.
:raises TypeError: If parameter 'parent' is not a Testclass or Testsuite.
"""
if parent is not None:
if not isinstance(parent, (Testclass, Testsuite)):
ex = TypeError("Parameter 'parent' is not of type 'Testclass' or 'Testsuite'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
parent._testcases[name] = self
super().__init__(name, duration, assertionCount, parent=parent)
TestcaseOutputMixin.__init__(self, message, details, standardOutput, standardError)
if not isinstance(status, TestcaseStatus):
ex = TypeError("Parameter 'status' is not of type 'TestcaseStatus'.")
ex.add_note(f"Got type '{getFullyQualifiedName(status)}'.")
raise ex
self._status = status
@readonly
def Classname(self) -> str:
"""
Read-only property to return the class name of the test case.
:returns: The test case's class name, or an empty string for a test case directly in a test suite.
.. note::
In the JUnit format, a test case is uniquely identified by a tuple of class name and test case name. This
structure has been decomposed by this data model into 2 leaf-levels in the test entity hierarchy. Thus, the class
name is represented by its own level and instances of test classes.
"""
if self._parent is None:
raise UnittestError("Standalone Testcase instance is not linked to a Testclass.")
elif isinstance(self._parent, Testsuite):
return ""
else:
return self._parent._name
@readonly
def Status(self) -> TestcaseStatus:
"""
Read-only property to access the status of the test case.
:returns: The test case's status.
"""
return self._status
@readonly
def AssertionCount(self) -> int:
"""
Read-only property to return the number of assertions (checks) in a test case.
.. note::
The JUnit format doesn't distinguish passed and failed assertions.
:returns: Number of assertions.
"""
if self._assertionCount is None:
return 0
return self._assertionCount
def Copy(self) -> Testcase:
return self.__class__(
self._name,
self._duration,
self._status,
self._assertionCount,
self._message,
self._details,
self._standardOutput,
self._standardError
)
def Aggregate(self) -> None:
if self._status is TestcaseStatus.Unknown:
if self._assertionCount is None:
self._status = TestcaseStatus.Passed
elif self._assertionCount == 0:
self._status = TestcaseStatus.Weak
else:
self._status = TestcaseStatus.Failed
# TODO: check for setup errors
# TODO: check for teardown errors
[docs]
@classmethod
def FromTestcase(cls, testcase: ut_Testcase) -> Testcase:
"""
Convert a test case of the unified test entity data model to the JUnit specific data model's test case object.
:param testcase: Test case from unified data model.
:returns: Test case from JUnit specific data model.
"""
return cls(
testcase._name,
duration=testcase._testDuration,
status= testcase._status,
assertionCount=testcase._assertionCount,
message=testcase._message,
details=testcase._details,
standardOutput=testcase._standardOutput,
standardError=testcase._standardError
)
def ToTestcase(self) -> ut_Testcase:
return ut_Testcase(
self._name,
testDuration=self._duration,
status=self._status,
assertionCount=self._assertionCount,
# TODO: as only assertions are recorded by JUnit files, all are marked as passed
passedAssertionCount=self._assertionCount,
message=self._message,
details=self._details,
standardOutput=self._standardOutput,
standardError=self._standardError
)
def ToTree(self) -> Node:
node = Node(value=self._name)
node["status"] = self._status
node["assertionCount"] = self._assertionCount
node["duration"] = self._duration
return node
[docs]
def __str__(self) -> str:
moduleName = self.__module__.split(".")[-1]
className = getTypeName(self)
return (
f"<{moduleName}{className} {self._name}: {self._status.name} - asserts:{self._assertionCount}>"
)
[docs]
@export
class TestsuiteBase(BaseWithProperties):
"""
Base-class for all test suites and for test summaries.
A test suite is a mid-level grouping element in the test entity hierarchy, whereas the test summary is the root
element in that hierarchy. While a test suite groups test classes, a test summary can only group test suites. Thus, a
test summary contains no test classes and test cases.
"""
_startTime: Nullable[datetime]
_status: TestsuiteStatus
_tests: int
_skipped: int
_errored: int
_weak: int
_failed: int
_passed: int
[docs]
def __init__(
self,
name: str,
startTime: Nullable[datetime] = None,
duration: Nullable[timedelta] = None,
status: TestsuiteStatus = TestsuiteStatus.Unknown,
*,
parent: Nullable[Testsuite] = None
) -> None:
"""
Initializes the based-class fields of a test suite or test summary.
:param name: Name of the test entity.
:param startTime: Optional, time when the test entity was started.
:param duration: Optional, duration of the entity's execution.
:param status: Optional, overall status of the test entity.
:param parent: Optional, reference to the parent test entity.
:raises TypeError: If parameter 'parent' is not a TestsuiteBase.
"""
if parent is not None:
if not isinstance(parent, TestsuiteBase):
ex = TypeError("Parameter 'parent' is not of type 'TestsuiteBase'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
parent._testsuites[name] = self
super().__init__(name, duration, None, parent=parent)
self._startTime = startTime
self._status = status
self._tests = 0
self._skipped = 0
self._errored = 0
self._failed = 0
self._passed = 0
@readonly
def StartTime(self) -> Nullable[datetime]:
"""
Read-only property to access the time the test entity's execution started.
:returns: Start time of the execution, or ``None`` if it wasn't recorded.
"""
return self._startTime
@readonly
def Status(self) -> TestsuiteStatus:
"""
Read-only property to access the test entity's aggregated status.
:returns: Status of the test entity.
"""
return self._status
@readonly
@mustoverride
def TestcaseCount(self) -> int:
"""
Read-only property to access the number of testcases in this entity.
:returns: Number of testcases.
"""
pass
@readonly
def Tests(self) -> int:
"""
Read-only property to access the number of testcases in this entity.
:returns: Number of testcases.
"""
return self.TestcaseCount
@readonly
def Skipped(self) -> int:
"""
Read-only property to access the number of skipped testcases.
:returns: Number of skipped testcases.
"""
return self._skipped
@readonly
def Errored(self) -> int:
"""
Read-only property to access the number of errored testcases.
:returns: Number of errored testcases.
"""
return self._errored
@readonly
def Failed(self) -> int:
"""
Read-only property to access the number of failed testcases.
:returns: Number of failed testcases.
"""
return self._failed
@readonly
def Passed(self) -> int:
"""
Read-only property to access the number of passed testcases.
:returns: Number of passed testcases.
"""
return self._passed
def Aggregate(self) -> TestsuiteAggregateReturnType:
tests = 0
skipped = 0
errored = 0
weak = 0
failed = 0
passed = 0
# for testsuite in self._testsuites.values():
# t, s, e, w, f, p = testsuite.Aggregate()
# tests += t
# skipped += s
# errored += e
# weak += w
# failed += f
# passed += p
return tests, skipped, errored, weak, failed, passed
@mustoverride
def Iterate(self, scheme: IterationScheme = IterationScheme.Default) -> Generator[Union[TestsuiteType, Testcase], None, None]:
pass
[docs]
@export
class Testclass(Base):
"""
A test class is a low-level element in the test entity hierarchy representing a group of tests.
Test classes contain test cases and are grouped by a test suites.
"""
_testcases: Dict[str, Testcase]
[docs]
def __init__(
self,
classname: str,
testcases: Nullable[Iterable[Testcase]] = None,
*,
parent: Nullable[Testsuite] = None
) -> None:
"""
Initializes the fields of the test class.
:param classname: Classname of the test entity.
:param parent: Optional, reference to the parent test suite.
:raises ValueError: If parameter 'classname' is None.
:raises TypeError: If parameter 'classname' is not a string.
:raises ValueError: If parameter 'classname' is empty.
"""
if parent is not None:
if not isinstance(parent, Testsuite):
ex = TypeError("Parameter 'parent' is not of type 'Testsuite'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
parent._testclasses[classname] = self
super().__init__(classname, parent=parent)
self._testcases = {}
if testcases is not None:
for testcase in testcases:
if testcase._parent is not None:
raise AlreadyInTestsuiteError(f"Testcase '{testcase._name}' is already part of a testsuite hierarchy.")
if testcase._name in self._testcases:
raise DuplicateTestcaseError(f"Class already contains a testcase with same name '{testcase._name}'.")
testcase._parent = self
self._testcases[testcase._name] = testcase
@readonly
def Classname(self) -> str:
"""
Read-only property to access the name of the test class.
:returns: The test class' name.
"""
return self._name
@readonly
def Testcases(self) -> Dict[str, Testcase]:
"""
Read-only property to access a reference to the internal dictionary of test cases.
:returns: Reference to the dictionary of test cases.
"""
return self._testcases
@readonly
def TestcaseCount(self) -> int:
"""
Read-only property to return the number of all test cases in the test entity hierarchy.
:returns: Number of test cases.
"""
return len(self._testcases)
@readonly
def AssertionCount(self) -> int:
"""
Read-only property to return the number of assertions across all testcases of this testclass.
:returns: Sum of the testcases' assertion counts.
"""
return sum(tc.AssertionCount for tc in self._testcases.values())
def AddTestcase(self, testcase: Testcase) -> None:
if testcase._parent is not None:
raise ValueError(f"Testcase '{testcase._name}' is already part of a testsuite hierarchy.")
if testcase._name in self._testcases:
raise DuplicateTestcaseError(f"Class already contains a testcase with same name '{testcase._name}'.")
testcase._parent = self
self._testcases[testcase._name] = testcase
def AddTestcases(self, testcases: Iterable[Testcase]) -> None:
for testcase in testcases:
self.AddTestcase(testcase)
def ToTestsuite(self) -> ut_Testsuite:
return ut_Testsuite(
self._name,
kind=TestsuiteKind.Class,
# startTime=self._startTime,
# totalDuration=self._duration,
# status=self._status,
testcases=(tc.ToTestcase() for tc in self._testcases.values())
)
def ToTree(self) -> Node:
node = Node(
value=self._name,
children=(tc.ToTree() for tc in self._testcases.values())
)
return node
[docs]
def __str__(self) -> str:
moduleName = self.__module__.split(".")[-1]
className = getTypeName(self)
return (
f"<{moduleName}{className} {self._name}: {len(self._testcases)}>"
)
[docs]
@export
class Testsuite(TestsuiteBase):
"""
A testsuite is a mid-level element in the test entity hierarchy representing a logical group of tests.
Test suites contain test classes and are grouped by a test summary, which is the root of the hierarchy. A test case
without a class (empty ``classname``) is contained in the test suite directly.
"""
_hostname: str
_testclasses: Dict[str, Testclass]
_testcases: Dict[str, Testcase] #: Test cases without a class, contained in the test suite directly.
[docs]
def __init__(
self,
name: str,
hostname: Nullable[str] = None,
startTime: Nullable[datetime] = None,
duration: Nullable[timedelta] = None,
status: TestsuiteStatus = TestsuiteStatus.Unknown,
testclasses: Nullable[Iterable[Testclass]] = None,
testcases: Nullable[Iterable[Testcase]] = None,
*,
parent: Nullable[TestsuiteSummary] = None
) -> None:
"""
Initializes the fields of a test suite.
:param name: Name of the test suite.
:param hostname: Optional, name of the host the test suite was executed on.
:param startTime: Optional, time when the test suite was started.
:param duration: Optional, duration of the entity's execution.
:param status: Optional, overall status of the test suite.
:param testclasses: Optional, test classes of the test suite.
:param testcases: Optional, test cases without a class, contained in the test suite directly.
:param parent: Optional, reference to the parent test summary.
:raises TypeError: If parameter 'testcases' is not iterable.
:raises TypeError: If an element of parameter 'testcases' is not a Testcase.
:raises AlreadyInTestsuiteError: If a test case in parameter 'testcases' is already part of a test entity hierarchy.
:raises DuplicateTestcaseError: If a test case in parameter 'testcases' is already listed (by name) in the list of
test cases.
:raises TypeError: If parameter 'parent' is not a TestsuiteSummary.
"""
if parent is not None:
if not isinstance(parent, TestsuiteSummary):
ex = TypeError("Parameter 'parent' is not of type 'TestsuiteSummary'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
parent._testsuites[name] = self
super().__init__(name, startTime, duration, status, parent=parent)
self._hostname = hostname
self._testclasses = {}
if testclasses is not None:
for testclass in testclasses:
if testclass._parent is not None:
raise ValueError(f"Class '{testclass._name}' is already part of a testsuite hierarchy.")
if testclass._name in self._testclasses:
raise DuplicateTestcaseError(f"Testsuite already contains a class with same name '{testclass._name}'.")
testclass._parent = self
self._testclasses[testclass._name] = testclass
self._testcases = {}
if testcases is not None:
if not isinstance(testcases, Iterable):
ex = TypeError("Parameter 'testcases' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(testcases)}'.")
raise ex
for testcase in testcases:
if not isinstance(testcase, Testcase):
ex = TypeError("Element of parameter 'testcases' is not of type 'Testcase'.")
ex.add_note(f"Got type '{getFullyQualifiedName(testcase)}'.")
raise ex
elif testcase._parent is not None:
raise AlreadyInTestsuiteError(f"Testcase '{testcase._name}' is already part of a testsuite hierarchy.")
if testcase._name in self._testcases:
raise DuplicateTestcaseError(f"Testsuite already contains a testcase with same name '{testcase._name}'.")
testcase._parent = self
self._testcases[testcase._name] = testcase
@readonly
def Hostname(self) -> Nullable[str]:
"""
Read-only property to access the host the testsuite was executed on.
:returns: Hostname, or ``None`` if it wasn't recorded.
"""
return self._hostname
@readonly
def Testclasses(self) -> Dict[str, Testclass]:
"""
Read-only property to access the testsuite's testclasses.
:returns: Dictionary of testclass names and testclasses.
"""
return self._testclasses
@readonly
def TestclassCount(self) -> int:
"""
Read-only property to return the number of testclasses in this testsuite.
:returns: Number of testclasses.
"""
return len(self._testclasses)
@readonly
def Testcases(self) -> Dict[str, Testcase]:
"""
Read-only property to access the testsuite's testcases without a class (:attr:`_testcases`).
:returns: Dictionary of testcase names and testcases.
"""
return self._testcases
@readonly
def TestcaseCount(self) -> int:
"""
Read-only property to return the number of testcases across all testclasses and of the testcases without a class.
:returns: Sum of the testclasses' testcase counts and the number of testcases without a class.
"""
return sum(cls.TestcaseCount for cls in self._testclasses.values()) + len(self._testcases)
@readonly
def AssertionCount(self) -> int:
"""
Read-only property to return the number of assertions across all testclasses and testcases without a class.
:returns: Sum of the testclasses' and the testcases' assertion counts.
"""
return (
sum(cls.AssertionCount for cls in self._testclasses.values()) +
sum(tc.AssertionCount for tc in self._testcases.values())
)
def AddTestclass(self, testclass: Testclass) -> None:
if testclass._parent is not None:
raise ValueError(f"Class '{testclass._name}' is already part of a testsuite hierarchy.")
if testclass._name in self._testclasses:
raise DuplicateTestcaseError(f"Testsuite already contains a class with same name '{testclass._name}'.")
testclass._parent = self
self._testclasses[testclass._name] = testclass
def AddTestclasses(self, testclasses: Iterable[Testclass]) -> None:
for testcase in testclasses:
self.AddTestclass(testcase)
[docs]
def AddTestcase(self, testcase: Testcase) -> None:
"""
Add a testcase without a class to the testsuite.
:param testcase: The testcase to add.
:raises ValueError: If parameter 'testcase' is None.
:raises TypeError: If parameter 'testcase' is not a Testcase.
:raises AlreadyInTestsuiteError: If the testcase is already part of a test entity hierarchy.
:raises DuplicateTestcaseError: If the testsuite already contains a testcase without a class by the same name.
"""
if testcase is None:
raise ValueError("Parameter 'testcase' is None.")
elif not isinstance(testcase, Testcase):
ex = TypeError("Parameter 'testcase' is not of type 'Testcase'.")
ex.add_note(f"Got type '{getFullyQualifiedName(testcase)}'.")
raise ex
elif testcase._parent is not None:
raise AlreadyInTestsuiteError(f"Testcase '{testcase._name}' is already part of a testsuite hierarchy.")
if testcase._name in self._testcases:
raise DuplicateTestcaseError(f"Testsuite already contains a testcase with same name '{testcase._name}'.")
testcase._parent = self
self._testcases[testcase._name] = testcase
[docs]
def AddTestcases(self, testcases: Iterable[Testcase]) -> None:
"""
Add testcases without a class to the testsuite.
:param testcases: The testcases to add.
:raises ValueError: If parameter 'testcases' is None.
:raises TypeError: If parameter 'testcases' is not iterable.
"""
if testcases is None:
raise ValueError("Parameter 'testcases' is None.")
elif not isinstance(testcases, Iterable):
ex = TypeError("Parameter 'testcases' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(testcases)}'.")
raise ex
for testcase in testcases:
self.AddTestcase(testcase)
# def IterateTestsuites(self, scheme: IterationScheme = IterationScheme.TestsuiteDefault) -> Generator[TestsuiteType, None, None]:
# return self.Iterate(scheme)
def IterateTestcases(self, scheme: IterationScheme = IterationScheme.TestcaseDefault) -> Generator[Testcase, None, None]:
return self.Iterate(scheme)
def Copy(self) -> Testsuite:
return self.__class__(
self._name,
self._hostname,
self._startTime,
self._duration,
self._status
)
def Aggregate(self, strict: bool = True) -> TestsuiteAggregateReturnType:
tests, skipped, errored, weak, failed, passed = super().Aggregate()
testcases = list(self._testcases.values())
for testclass in self._testclasses.values():
testcases.extend(testclass._testcases.values())
for testcase in testcases:
_ = testcase.Aggregate()
tests += 1
status = testcase._status
if status is TestcaseStatus.Unknown:
raise UnittestError(f"Found testcase '{testcase._name}' with state 'Unknown'.")
elif status is TestcaseStatus.Skipped:
skipped += 1
elif status is TestcaseStatus.Errored:
errored += 1
elif status is TestcaseStatus.Passed:
passed += 1
elif status is TestcaseStatus.Failed:
failed += 1
elif status is TestcaseStatus.Weak:
weak += 1
elif status & TestcaseStatus.Mask is not TestcaseStatus.Unknown:
raise UnittestError(f"Found testcase '{testcase._name}' with unsupported state '{status}'.")
else:
raise UnittestError(f"Internal error for testcase '{testcase._name}', field '_status' is '{status}'.")
self._tests = tests
self._skipped = skipped
self._errored = errored
self._weak = weak
self._failed = failed
self._passed = passed
# FIXME: weak?
if errored > 0:
self._status = TestsuiteStatus.Errored
elif failed > 0:
self._status = TestsuiteStatus.Failed
elif tests == 0:
self._status = TestsuiteStatus.Empty
elif tests - skipped == passed:
self._status = TestsuiteStatus.Passed
elif tests == skipped:
self._status = TestsuiteStatus.Skipped
else:
self._status = TestsuiteStatus.Unknown
return tests, skipped, errored, weak, failed, passed
[docs]
def Iterate(self, scheme: IterationScheme = IterationScheme.Default) -> Generator[Union[TestsuiteType, Testcase], None, None]:
"""
Iterate the test suite and its child elements according to the iteration scheme.
If no scheme is given, use the default scheme.
:param scheme: Optional, scheme how to iterate the test suite and its child elements.
:returns: A generator for iterating the results filtered and in the order defined by the iteration scheme.
"""
if IterationScheme.PreOrder in scheme:
if IterationScheme.IncludeSelf | IterationScheme.IncludeTestsuites in scheme:
yield self
if IterationScheme.IncludeTestcases in scheme:
for testcase in self._testcases.values():
yield testcase
for testclass in self._testclasses.values():
yield from testclass.Iterate(scheme | IterationScheme.IncludeSelf)
if IterationScheme.PostOrder in scheme:
if IterationScheme.IncludeTestcases in scheme:
for testcase in self._testcases.values():
yield testcase
if IterationScheme.IncludeSelf | IterationScheme.IncludeTestsuites in scheme:
yield self
[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.
:param testsuite: Test suite from unified data model.
:returns: Test suite from JUnit specific data model.
"""
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
def ToTestsuite(self) -> ut_Testsuite:
testsuite = ut_Testsuite(
self._name,
kind=TestsuiteKind.Logical,
hostname=self._hostname,
startTime=self._startTime,
totalDuration=self._duration,
status=self._status,
testcases=(tc.ToTestcase() for tc in self._testcases.values())
)
for testclass in self._testclasses.values():
suite = testsuite
classpath = testclass._name.split(".")
for element in classpath:
if element in suite._testsuites:
suite = suite._testsuites[element]
else:
suite = ut_Testsuite(element, kind=TestsuiteKind.Package, parent=suite)
suite._kind = TestsuiteKind.Class
if suite._parent is not testsuite:
suite._parent._kind = TestsuiteKind.Module
suite.AddTestcases(tc.ToTestcase() for tc in testclass._testcases.values())
return testsuite
def ToTree(self) -> Node:
node = Node(
value=self._name,
children=(
*(tc.ToTree() for tc in self._testcases.values()),
*(cls.ToTree() for cls in self._testclasses.values())
)
)
node["startTime"] = self._startTime
node["duration"] = self._duration
return node
[docs]
def __str__(self) -> str:
moduleName = self.__module__.split(".")[-1]
className = getTypeName(self)
return (
f"<{moduleName}{className} {self._name}: {self._status.name} - tests:{self._tests}>"
)
[docs]
@export
class TestsuiteSummary(TestsuiteBase):
_testsuites: Dict[str, Testsuite]
[docs]
def __init__(
self,
name: str,
startTime: Nullable[datetime] = None,
duration: Nullable[timedelta] = None,
status: TestsuiteStatus = TestsuiteStatus.Unknown,
testsuites: Nullable[Iterable[Testsuite]] = None
) -> None:
super().__init__(name, startTime, duration, status)
self._testsuites = {}
if testsuites is not None:
for testsuite in testsuites:
if testsuite._parent is not None:
raise ValueError(f"Testsuite '{testsuite._name}' is already part of a testsuite hierarchy.")
if testsuite._name in self._testsuites:
raise DuplicateTestsuiteError(f"Testsuite already contains a testsuite with same name '{testsuite._name}'.")
testsuite._parent = self
self._testsuites[testsuite._name] = testsuite
@readonly
def Testsuites(self) -> Dict[str, Testsuite]:
"""
Read-only property to access the summary's testsuites.
:returns: Dictionary of testsuite names and testsuites.
"""
return self._testsuites
@readonly
def TestcaseCount(self) -> int:
"""
Read-only property to return the number of testcases across all testsuites.
:returns: Sum of the testsuites' testcase counts.
"""
return sum(ts.TestcaseCount for ts in self._testsuites.values())
@readonly
def TestsuiteCount(self) -> int:
"""
Read-only property to return the number of testsuites in this summary.
:returns: Number of testsuites.
"""
return len(self._testsuites)
@readonly
def AssertionCount(self) -> int:
"""
Read-only property to return the number of assertions across all testsuites.
:returns: Sum of the testsuites' assertion counts.
"""
return sum(ts.AssertionCount for ts in self._testsuites.values())
def AddTestsuite(self, testsuite: Testsuite) -> None:
if testsuite._parent is not None:
raise ValueError(f"Testsuite '{testsuite._name}' is already part of a testsuite hierarchy.")
if testsuite._name in self._testsuites:
raise DuplicateTestsuiteError(f"Testsuite already contains a testsuite with same name '{testsuite._name}'.")
testsuite._parent = self
self._testsuites[testsuite._name] = testsuite
def AddTestsuites(self, testsuites: Iterable[Testsuite]) -> None:
for testsuite in testsuites:
self.AddTestsuite(testsuite)
def Aggregate(self) -> TestsuiteAggregateReturnType:
tests, skipped, errored, weak, failed, passed = super().Aggregate()
for testsuite in self._testsuites.values():
t, s, e, w, f, p = testsuite.Aggregate()
tests += t
skipped += s
errored += e
weak += w
failed += f
passed += p
self._tests = tests
self._skipped = skipped
self._errored = errored
self._weak = weak
self._failed = failed
self._passed = passed
# FIXME: weak
if errored > 0:
self._status = TestsuiteStatus.Errored
elif failed > 0:
self._status = TestsuiteStatus.Failed
elif tests == 0:
self._status = TestsuiteStatus.Empty
elif tests - skipped == passed:
self._status = TestsuiteStatus.Passed
elif tests == skipped:
self._status = TestsuiteStatus.Skipped
else:
self._status = TestsuiteStatus.Unknown
return tests, skipped, errored, weak, failed, passed
[docs]
def Iterate(self, scheme: IterationScheme = IterationScheme.Default) -> Generator[Union[Testsuite, Testcase], None, None]:
"""
Iterate the test suite summary and its child elements according to the iteration scheme.
If no scheme is given, use the default scheme.
:param scheme: Optional, scheme how to iterate the test suite summary and its child elements.
:returns: A generator for iterating the results filtered and in the order defined by the iteration scheme.
"""
if IterationScheme.IncludeSelf | IterationScheme.IncludeTestsuites | IterationScheme.PreOrder in scheme:
yield self
for testsuite in self._testsuites.values():
yield from testsuite.IterateTestsuites(scheme | IterationScheme.IncludeSelf)
if IterationScheme.IncludeSelf | IterationScheme.IncludeTestsuites | IterationScheme.PostOrder in scheme:
yield self
[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.
:param testsuiteSummary: Test suite summary from unified data model.
:returns: Test suite summary from JUnit specific data model.
"""
return cls(
testsuiteSummary._name,
startTime=testsuiteSummary._startTime,
duration=testsuiteSummary._totalDuration,
status=testsuiteSummary._status,
testsuites=(Testsuite.FromTestsuite(testsuite) for testsuite in testsuiteSummary._testsuites.values())
)
[docs]
def ToTestsuiteSummary(self) -> ut_TestsuiteSummary:
"""
Convert this test suite summary a new test suite summary of the unified data model.
All fields are copied to the new instance. Child elements like test suites are copied recursively.
:returns: A test suite summary of the unified test entity data model.
"""
return ut_TestsuiteSummary(
self._name,
startTime=self._startTime,
totalDuration=self._duration,
status=self._status,
testsuites=(testsuite.ToTestsuite() for testsuite in self._testsuites.values())
)
def ToTree(self) -> Node:
node = Node(
value=self._name,
children=(ts.ToTree() for ts in self._testsuites.values())
)
node["startTime"] = self._startTime
node["duration"] = self._duration
return node
[docs]
def __str__(self) -> str:
moduleName = self.__module__.split(".")[-1]
className = getTypeName(self)
return (
f"<{moduleName}{className} {self._name}: {self._status.name} - tests:{self._tests}>"
)
[docs]
@export
class Document(TestsuiteSummary, ut_Document):
_DIALECT: ClassVar[str] = "Any-JUnit"
_TESTCASE: ClassVar[Type[Testcase]] = Testcase
_TESTCLASS: ClassVar[Type[Testclass]] = Testclass
_TESTSUITE: ClassVar[Type[Testsuite]] = Testsuite
_readerMode: JUnitReaderMode
_xmlDocument: Nullable[_ElementTree]
[docs]
def __init__(
self,
xmlReportFile: Path,
analyzeAndConvert: bool = False,
readerMode: JUnitReaderMode = JUnitReaderMode.Default,
*,
name: str = "Unprocessed JUnit XML file",
startTime: Nullable[datetime] = None,
duration: Nullable[timedelta] = None,
status: TestsuiteStatus = TestsuiteStatus.Unknown,
testsuites: Nullable[Iterable[Testsuite]] = None
) -> None:
"""
Initializes a JUnit XML document, read from or written to a file.
:param xmlReportFile: Path to the JUnit XML file.
:param analyzeAndConvert: Optional, if true, analyze (parse and validate) the file and convert its content.
:param readerMode: Optional, how strictly the file is read.
:param name: Optional, name of the test suite summary.
:param startTime: Optional, time when the test run was started.
:param duration: Optional, duration of the test run.
:param status: Optional, overall status of the test run.
:param testsuites: Optional, test suites of the summary.
"""
super().__init__(name, startTime, duration, status, testsuites)
self._readerMode = readerMode
self._xmlDocument = None
ut_Document.__init__(self, xmlReportFile, analyzeAndConvert)
[docs]
@classmethod
def FromTestsuiteSummary(cls, xmlReportFile: Path, testsuiteSummary: ut_TestsuiteSummary) -> Document:
"""
Convert a test suite summary of the unified test entity data model to a JUnit XML document of this dialect.
The test suites become test suites of the dialect (:attr:`_TESTSUITE`). The counters are computed by
:meth:`Aggregate`.
:param xmlReportFile: Path to the JUnit XML file to write.
:param testsuiteSummary: Test suite summary from unified data model.
:returns: JUnit XML document of this dialect.
"""
doc = cls(
xmlReportFile,
name=testsuiteSummary._name,
startTime=testsuiteSummary._startTime,
duration=testsuiteSummary._totalDuration,
status=testsuiteSummary._status,
testsuites=(cls._TESTSUITE.FromTestsuite(testsuite) for testsuite in testsuiteSummary._testsuites.values())
)
doc.Aggregate()
return doc
[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 generic to support "any" dialect.
"""
xmlSchemaFile = "Any-JUnit.xsd"
self._Analyze(xmlSchemaFile)
def _Analyze(self, xmlSchemaFile: str) -> None:
if not self._path.exists():
raise UnittestError(f"JUnit XML file '{self._path}' does not exist.") \
from FileNotFoundError(f"File '{self._path}' not found.")
with Stopwatch() as sw:
try:
xmlSchemaResourceFile = getResourceFile(Resources, xmlSchemaFile)
except ToolingException as ex:
raise UnittestError(f"Couldn't locate XML Schema '{xmlSchemaFile}' in package resources.") from ex
try:
schemaParser = XMLParser(ns_clean=True)
schemaRoot = parse(xmlSchemaResourceFile, schemaParser)
except XMLSyntaxError as ex:
raise UnittestError(f"XML Syntax Error while parsing XML Schema '{xmlSchemaFile}'.") from ex
try:
junitSchema = XMLSchema(schemaRoot)
except XMLSchemaParseError as ex:
raise UnittestError(f"Error while parsing XML Schema '{xmlSchemaFile}'.") from ex
try:
content = self._path.read_bytes()
except OSError as ex:
raise UnittestError(f"Couldn't read JUnit XML file '{self._path}'.") from ex
junitParser = XMLParser(schema=junitSchema, ns_clean=True)
try:
self._xmlDocument = parse(BytesIO(content), parser=junitParser, base_url=str(self._path))
except XMLSyntaxError as ex:
for logEntry in junitParser.error_log:
ex.add_note(str(logEntry))
raise UnittestError(
f"XML syntax or validation error for '{self._path}' using XSD schema '{xmlSchemaResourceFile}'."
) from ex
self._analysisDuration = sw.Duration
[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 Any JUnit 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)
self._startTime = self._ConvertTimestamp(rootElement, optional=True)
self._duration = self._ConvertTime(rootElement, optional=True)
if False: # self._readerMode is JUnitReaderMode.
self._tests = self._ConvertTests(testsuitesNode)
self._skipped = self._ConvertSkipped(testsuitesNode)
self._errored = self._ConvertErrors(testsuitesNode)
self._failed = self._ConvertFailures(testsuitesNode)
self._assertionCount = self._ConvertAssertions(testsuitesNode)
for rootNode in rootElement.iterchildren(tag="testsuite"): # type: _Element
self._ConvertTestsuite(self, rootNode)
if True: # self._readerMode is JUnitReaderMode.
self.Aggregate()
self._modelConversion = sw.Duration
[docs]
def _ConvertName(self, element: _Element, default: str = "root", optional: bool = True) -> str:
"""
Convert the ``name`` attribute from an XML element node to a string.
:param element: The XML element node with a ``name`` attribute.
:param default: Optional, the default value, if no ``name`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``name`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``name`` attribute exists on the given element node.
"""
if "name" in element.attrib:
return element.attrib["name"]
elif not optional:
raise UnittestError(f"Required parameter 'name' not found in tag '{element.tag}'.")
else:
return default
[docs]
def _ConvertTimestamp(self, element: _Element, optional: bool = True) -> Nullable[datetime]:
"""
Convert the ``timestamp`` attribute from an XML element node to a datetime.
:param element: The XML element node with a ``timestamp`` attribute.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``timestamp`` attribute's content if found, otherwise ``None``.
:raises UnittestError: If optional is false and no ``timestamp`` attribute exists on the given element node.
"""
if "timestamp" in element.attrib:
timestamp = element.attrib["timestamp"]
return datetime.fromisoformat(timestamp)
elif not optional:
raise UnittestError(f"Required parameter 'timestamp' not found in tag '{element.tag}'.")
else:
return None
[docs]
def _ConvertTime(self, element: _Element, optional: bool = True) -> Nullable[timedelta]:
"""
Convert the ``time`` attribute from an XML element node to a timedelta.
:param element: The XML element node with a ``time`` attribute.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``time`` attribute's content if found, otherwise ``None``.
:raises UnittestError: If optional is false and no ``time`` attribute exists on the given element node.
"""
if "time" in element.attrib:
time = element.attrib["time"]
return timedelta(seconds=float(time))
elif not optional:
raise UnittestError(f"Required parameter 'time' not found in tag '{element.tag}'.")
else:
return None
[docs]
def _ConvertHostname(self, element: _Element, default: str = "localhost", optional: bool = True) -> str:
"""
Convert the ``hostname`` attribute from an XML element node to a string.
:param element: The XML element node with a ``hostname`` attribute.
:param default: Optional, the default value, if no ``hostname`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``hostname`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``hostname`` attribute exists on the given element node.
"""
if "hostname" in element.attrib:
return element.attrib["hostname"]
elif not optional:
raise UnittestError(f"Required parameter 'hostname' not found in tag '{element.tag}'.")
else:
return default
[docs]
def _ConvertClassname(self, element: _Element) -> str:
"""
Convert the ``classname`` attribute from an XML element node to a string.
:param element: The XML element node with a ``classname`` attribute.
:returns: The ``classname`` attribute's content.
:raises UnittestError: If no ``classname`` attribute exists on the given element node.
"""
if "classname" in element.attrib:
return element.attrib["classname"]
else:
raise UnittestError(f"Required parameter 'classname' not found in tag '{element.tag}'.")
[docs]
def _ConvertTests(self, element: _Element, default: Nullable[int] = None, optional: bool = True) -> Nullable[int]:
"""
Convert the ``tests`` attribute from an XML element node to an integer.
:param element: The XML element node with a ``tests`` attribute.
:param default: Optional, the default value, if no ``tests`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``tests`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``tests`` attribute exists on the given element node.
"""
if "tests" in element.attrib:
return int(element.attrib["tests"])
elif not optional:
raise UnittestError(f"Required parameter 'tests' not found in tag '{element.tag}'.")
else:
return default
[docs]
def _ConvertSkipped(self, element: _Element, default: Nullable[int] = None, optional: bool = True) -> Nullable[int]:
"""
Convert the ``skipped`` attribute from an XML element node to an integer.
:param element: The XML element node with a ``skipped`` attribute.
:param default: Optional, the default value, if no ``skipped`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``skipped`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``skipped`` attribute exists on the given element node.
"""
if "skipped" in element.attrib:
return int(element.attrib["skipped"])
elif not optional:
raise UnittestError(f"Required parameter 'skipped' not found in tag '{element.tag}'.")
else:
return default
[docs]
def _ConvertErrors(self, element: _Element, default: Nullable[int] = None, optional: bool = True) -> Nullable[int]:
"""
Convert the ``errors`` attribute from an XML element node to an integer.
:param element: The XML element node with a ``errors`` attribute.
:param default: Optional, the default value, if no ``errors`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``errors`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``errors`` attribute exists on the given element node.
"""
if "errors" in element.attrib:
return int(element.attrib["errors"])
elif not optional:
raise UnittestError(f"Required parameter 'errors' not found in tag '{element.tag}'.")
else:
return default
[docs]
def _ConvertFailures(self, element: _Element, default: Nullable[int] = None, optional: bool = True) -> Nullable[int]:
"""
Convert the ``failures`` attribute from an XML element node to an integer.
:param element: The XML element node with a ``failures`` attribute.
:param default: Optional, the default value, if no ``failures`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``failures`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``failures`` attribute exists on the given element node.
"""
if "failures" in element.attrib:
return int(element.attrib["failures"])
elif not optional:
raise UnittestError(f"Required parameter 'failures' not found in tag '{element.tag}'.")
else:
return default
[docs]
def _ConvertAssertions(self, element: _Element, default: Nullable[int] = None, optional: bool = True) -> Nullable[int]:
"""
Convert the ``assertions`` attribute from an XML element node to an integer.
:param element: The XML element node with a ``assertions`` attribute.
:param default: Optional, the default value, if no ``assertions`` attribute was found.
:param optional: Optional, if false, an exception is raised for the missing attribute.
:returns: The ``assertions`` attribute's content if found, otherwise the given default value.
:raises UnittestError: If optional is false and no ``assertions`` attribute exists on the given element node.
"""
if "assertions" in element.attrib:
return int(element.attrib["assertions"])
elif not optional:
raise UnittestError(f"Required parameter 'assertions' not found in tag '{element.tag}'.")
else:
return default
[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 = self._TESTSUITE(
self._ConvertName(testsuitesNode, optional=False),
self._ConvertHostname(testsuitesNode, optional=True),
self._ConvertTimestamp(testsuitesNode, optional=True),
self._ConvertTime(testsuitesNode, optional=True),
parent=parent
)
if False: # self._readerMode is JUnitReaderMode.
self._tests = self._ConvertTests(testsuitesNode)
self._skipped = self._ConvertSkipped(testsuitesNode)
self._errored = self._ConvertErrors(testsuitesNode)
self._failed = self._ConvertFailures(testsuitesNode)
self._assertionCount = self._ConvertAssertions(testsuitesNode)
self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite)
def _ConvertTestsuiteChildren(self, testsuitesNode: _Element, newTestsuite: Testsuite) -> None:
for node in testsuitesNode.iterchildren(): # type: _Element
# if node.tag == "testsuite":
# self._ConvertTestsuite(newTestsuite, node)
# el
if node.tag == "testcase":
self._ConvertTestcase(newTestsuite, node)
[docs]
def _ConvertTestcase(self, parent: Testsuite, testcaseNode: _Element) -> None:
"""
Convert the XML data structure of a ``<testcase>`` to a test case.
This method uses private helper methods provided by the base-class.
:param parent: The test suite as a parent element in the test entity hierarchy.
:param testcaseNode: The current XML element node representing a test case.
"""
className = self._ConvertClassname(testcaseNode)
if className == "":
testcaseParent = parent
else:
testcaseParent = self._FindOrCreateTestclass(parent, className)
newTestcase = self._TESTCASE(
self._ConvertName(testcaseNode, optional=False),
self._ConvertTime(testcaseNode, optional=True),
assertionCount=self._ConvertAssertions(testcaseNode),
parent=testcaseParent
)
self._ConvertTestcaseChildren(testcaseNode, newTestcase)
def _FindOrCreateTestclass(self, parent: Testsuite, className: str) -> Testclass:
if className in parent._testclasses:
return parent._testclasses[className]
else:
return self._TESTCLASS(className, parent=parent)
[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 ``<skipped>``, ``<failure>`` or ``<error>`` element sets the status. Its ``message`` attribute becomes the test
case's message, its text becomes the test case's details. The texts of ``<system-out>`` and ``<system-err>``
become the captured standard output and standard error; multiple such elements are concatenated. The reruns of a
test case (``<flakyFailure>``, ``<flakyError>``, ``<rerunFailure>`` and ``<rerunError>``) don't change its status.
: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.
"""
for node in testcaseNode.iterchildren(): # type: _Element
if isinstance(node, _Comment):
pass
elif isinstance(node, _Element):
if node.tag == "skipped":
newTestcase._status = TestcaseStatus.Skipped
self._ConvertStatusMessage(node, newTestcase)
elif node.tag == "failure":
newTestcase._status = TestcaseStatus.Failed
self._ConvertStatusMessage(node, newTestcase)
elif node.tag == "error":
newTestcase._status = TestcaseStatus.Errored
self._ConvertStatusMessage(node, newTestcase)
elif node.tag == "system-out":
if node.text is None:
pass
elif newTestcase._standardOutput is None:
newTestcase._standardOutput = node.text
else:
newTestcase._standardOutput += node.text
elif node.tag == "system-err":
if node.text is None:
pass
elif newTestcase._standardError is None:
newTestcase._standardError = node.text
else:
newTestcase._standardError += node.text
elif node.tag in ("properties", "flakyFailure", "flakyError", "rerunFailure", "rerunError"):
pass
else:
raise UnittestError(f"Unknown element '{node.tag}' in junit file.")
else:
pass
if newTestcase._status is TestcaseStatus.Unknown:
newTestcase._status = TestcaseStatus.Passed
[docs]
def _ConvertStatusMessage(self, element: _Element, testcase: Testcase) -> None:
"""
Convert the ``message`` attribute and the text of a ``<skipped>``, ``<failure>`` or ``<error>`` element.
An empty text (only whitespace) is not recorded.
:param element: The XML element node explaining the test case's status.
:param testcase: The test case to update.
"""
testcase._message = element.attrib.get("message", None)
testcase._details = None if element.text is None or element.text.strip() == "" else element.text
[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._startTime is not None:
rootElement.attrib["timestamp"] = f"{self._startTime.isoformat()}"
if self._duration is not None:
rootElement.attrib["time"] = f"{self._duration.total_seconds():.6f}"
rootElement.attrib["tests"] = str(self._tests)
rootElement.attrib["failures"] = str(self._failed)
rootElement.attrib["errors"] = str(self._errored)
rootElement.attrib["skipped"] = str(self._skipped)
# if self._assertionCount is not None:
# rootElement.attrib["assertions"] = f"{self._assertionCount}"
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.
: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.
"""
testsuiteElement = SubElement(parentElement, "testsuite")
testsuiteElement.attrib["name"] = testsuite._name
if testsuite._startTime is not None:
testsuiteElement.attrib["timestamp"] = f"{testsuite._startTime.isoformat()}"
if testsuite._duration is not None:
testsuiteElement.attrib["time"] = f"{testsuite._duration.total_seconds():.6f}"
testsuiteElement.attrib["tests"] = str(testsuite._tests)
testsuiteElement.attrib["failures"] = str(testsuite._failed)
testsuiteElement.attrib["errors"] = str(testsuite._errored)
testsuiteElement.attrib["skipped"] = str(testsuite._skipped)
# if testsuite._assertionCount is not None:
# testsuiteElement.attrib["assertions"] = f"{testsuite._assertionCount}"
if testsuite._hostname is not None:
testsuiteElement.attrib["hostname"] = testsuite._hostname
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")
if testcase.Classname is not None:
testcaseElement.attrib["classname"] = testcase.Classname
testcaseElement.attrib["name"] = testcase._name
if testcase._duration is not None:
testcaseElement.attrib["time"] = f"{testcase._duration.total_seconds():.6f}"
if testcase._assertionCount is not None:
testcaseElement.attrib["assertions"] = f"{testcase._assertionCount}"
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.
A failed, skipped or errored test case gets a ``<failure>``, ``<skipped>`` or ``<error>`` element carrying the
message (``message`` attribute) and details (text). Captured standard output and standard error are written as
``<system-out>`` and ``<system-err>`` elements.
:param testcase: The test case to convert to XML child elements.
:param testcaseElement: The ``<testcase>`` element, the child elements will be added to.
"""
if testcase._status is TestcaseStatus.Passed:
statusElement = None
elif testcase._status is TestcaseStatus.Failed:
statusElement = SubElement(testcaseElement, "failure")
elif testcase._status is TestcaseStatus.Skipped:
statusElement = SubElement(testcaseElement, "skipped")
else:
statusElement = SubElement(testcaseElement, "error")
if statusElement is not None:
if testcase._message is not None:
statusElement.attrib["message"] = testcase._message
if testcase._details is not None:
statusElement.text = testcase._details
if testcase._standardOutput is not None:
SubElement(testcaseElement, "system-out").text = testcase._standardOutput
if testcase._standardError is not None:
SubElement(testcaseElement, "system-err").text = testcase._standardError
[docs]
def __str__(self) -> str:
moduleName = self.__module__.split(".")[-1]
className = getTypeName(self)
return (
f"<{moduleName}{className} {self._name} ({self._path}): {self._status.name} - suites/tests:{self.TestsuiteCount}/{self.TestcaseCount}>"
)