Coverage for pyEDAA/Reports/Unittesting/JUnit/TestLoggerJUnit.py: 91%

1# ==================================================================================================================== # 

2# _____ ____ _ _ ____ _ # 

3# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ # 

4# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| # 

5# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ # 

6# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ # 

7# |_| |___/ |_| # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2026-2026 Electronic Design Automation Abstraction (EDA²) # 

15# # 

16# Licensed under the Apache License, Version 2.0 (the "License"); # 

17# you may not use this file except in compliance with the License. # 

18# You may obtain a copy of the License at # 

19# # 

20# http://www.apache.org/licenses/LICENSE-2.0 # 

21# # 

22# Unless required by applicable law or agreed to in writing, software # 

23# distributed under the License is distributed on an "AS IS" BASIS, # 

24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

25# See the License for the specific language governing permissions and # 

26# limitations under the License. # 

27# # 

28# SPDX-License-Identifier: Apache-2.0 # 

29# ==================================================================================================================== # 

30# 

31""" 

32Reader and writer for the JUnit XML dialect of the .NET test logger ``JunitXml.TestLogger``. 

33 

34The logger writes it, when ``dotnet test`` is called with ``--logger junit``. 

35 

36.. seealso:: 

37 

38 :ref:`UNITTEST/SpecificDataModel/JUnit/Dialect/TestLogger` 

39 |rarr| How the logger's report is read into the unified data model. 

40""" 

41from __future__ import annotations 

42 

43from datetime import timezone 

44from pathlib import Path 

45from typing import Optional as Nullable, ClassVar, Type 

46 

47from lxml.etree import ElementTree, Element, SubElement, tostring, _Element 

48from pyTooling.Common import firstValue 

49from pyTooling.Decorators import export, InheritDocString, DocStringMergeStrategy 

50from pyTooling.Stopwatch import Stopwatch 

51 

52from pyEDAA.Reports.Unittesting import UnittestError, TestcaseStatus, TestsuiteKind, \ 

53 TestsuiteSummary as ut_TestsuiteSummary, Testsuite as ut_Testsuite 

54from pyEDAA.Reports.Unittesting.JUnit import Testcase as ju_Testcase, Testclass as ju_Testclass, \ 

55 Testsuite as ju_Testsuite, TestsuiteSummary as ju_TestsuiteSummary, \ 

56 Document as ju_Document 

57 

58 

59@export 

60@InheritDocString(ju_Testcase, DocStringMergeStrategy.BaseLast) 

61class Testcase(ju_Testcase): 

62 """ 

63 This is a derived implementation for the JunitXml.TestLogger JUnit dialect. 

64 """ 

65 

66 

67@export 

68@InheritDocString(ju_Testclass, DocStringMergeStrategy.BaseLast) 

69class Testclass(ju_Testclass): 

70 """ 

71 This is a derived implementation for the JunitXml.TestLogger JUnit dialect. 

72 """ 

73 

74 

75@export 

76@InheritDocString(ju_Testsuite, DocStringMergeStrategy.BaseLast) 

77class Testsuite(ju_Testsuite): 

78 """ 

79 This is a derived implementation for the JunitXml.TestLogger JUnit dialect. 

80 """ 

81 

82 @classmethod 

83 def FromTestsuite(cls, testsuite: ut_Testsuite) -> Testsuite: 

84 """ 

85 Convert a test suite of the unified test entity data model to the JUnit specific data model's test suite object 

86 adhering to the JunitXml.TestLogger JUnit dialect. 

87 

88 :param testsuite: Test suite from unified data model. 

89 :returns: Test suite from JUnit specific data model (JunitXml.TestLogger JUnit dialect). 

90 :raises UnittestError: If a test case is not part of a test suite hierarchy. 

91 """ 

92 juTestsuite = cls( 

93 testsuite._name, 

94 hostname=testsuite._hostname, 

95 startTime=testsuite._startTime, 

96 duration=testsuite._totalDuration, 

97 status=testsuite._status, 

98 ) 

99 

100 for tc in testsuite.IterateTestcases(): 

101 ts = tc._parent 

102 if ts is None: 102 ↛ 103line 102 didn't jump to line 103 because the condition on line 102 was never true

103 raise UnittestError(f"Testcase '{tc._name}' is not part of a hierarchy.") 

104 elif ts is testsuite: 

105 juTestsuite.AddTestcase(Testcase.FromTestcase(tc)) 

106 continue 

107 

108 classname = ts._name 

109 ts = ts._parent 

110 while ts is not None and ts._kind > TestsuiteKind.Logical: 

111 classname = f"{ts._name}.{classname}" 

112 ts = ts._parent 

113 

114 if classname in juTestsuite._testclasses: 

115 juClass = juTestsuite._testclasses[classname] 

116 else: 

117 juClass = Testclass(classname, parent=juTestsuite) 

118 

119 juClass.AddTestcase(Testcase.FromTestcase(tc)) 

120 

121 return juTestsuite 

122 

123 def ToTestsuite(self) -> ut_Testsuite: 

124 """ 

125 Convert this test suite to a test suite of the unified test entity data model. 

126 

127 A test class' name is split into its namespace and its class at the last dot before the arguments of a 

128 parameterized test class. Each part of the namespace becomes a test suite of kind 

129 :attr:`~pyEDAA.Reports.Unittesting.TestsuiteKind.Namespace`, the class a test suite of kind 

130 :attr:`~pyEDAA.Reports.Unittesting.TestsuiteKind.Class` holding the test cases. A nested class keeps the name .NET 

131 gives it, e.g. ``Outer+Inner``. 

132 

133 :returns: Test suite of the unified test entity data model. 

134 """ 

135 testsuite = ut_Testsuite( 

136 self._name, 

137 kind=TestsuiteKind.Logical, 

138 hostname=self._hostname, 

139 startTime=self._startTime, 

140 totalDuration=self._duration, 

141 status=self._status, 

142 testcases=(tc.ToTestcase() for tc in self._testcases.values()) 

143 ) 

144 

145 for testclass in self._testclasses.values(): 

146 namespace, separator, _ = testclass._name.partition("(")[0].rpartition(".") 

147 

148 suite = testsuite 

149 if namespace != "": 

150 for element in namespace.split("."): 

151 if element in suite._testsuites: 

152 suite = suite._testsuites[element] 

153 else: 

154 suite = ut_Testsuite(element, kind=TestsuiteKind.Namespace, parent=suite) 

155 

156 ut_Testsuite( 

157 testclass._name[len(namespace) + len(separator):], 

158 kind=TestsuiteKind.Class, 

159 testcases=(tc.ToTestcase() for tc in testclass._testcases.values()), 

160 parent=suite 

161 ) 

162 

163 return testsuite 

164 

165 

166@export 

167@InheritDocString(ju_TestsuiteSummary, DocStringMergeStrategy.BaseLast) 

168class TestsuiteSummary(ju_TestsuiteSummary): 

169 """ 

170 This is a derived implementation for the JunitXml.TestLogger JUnit dialect. 

171 """ 

172 

173 @classmethod 

174 def FromTestsuiteSummary(cls, testsuiteSummary: ut_TestsuiteSummary) -> TestsuiteSummary: 

175 """ 

176 Convert a test suite summary of the unified test entity data model to the JUnit specific data model's test suite 

177 summary object adhering to the JunitXml.TestLogger JUnit dialect. 

178 

179 :param testsuiteSummary: Test suite summary from unified data model. 

180 :returns: Test suite summary from JUnit specific data model (JunitXml.TestLogger JUnit dialect). 

181 """ 

182 return cls( 

183 testsuiteSummary._name, 

184 startTime=testsuiteSummary._startTime, 

185 duration=testsuiteSummary._totalDuration, 

186 status=testsuiteSummary._status, 

187 testsuites=(Testsuite.FromTestsuite(testsuite) for testsuite in testsuiteSummary._testsuites.values()) 

188 ) 

189 

190 

191@export 

192class Document(ju_Document): 

193 """ 

194 A document reader and writer for the JunitXml.TestLogger JUnit XML file format. 

195 

196 This class reads, validates and transforms an XML file in the JunitXml.TestLogger JUnit format into a JUnit data 

197 model. It can then be converted into a unified test entity data model. 

198 

199 In reverse, a JUnit data model instance with the specific JunitXml.TestLogger JUnit file format can be created from a 

200 unified test entity data model. This data model can be written as XML into a file. 

201 """ 

202 

203 _DIALECT: ClassVar[str] = "JunitXml.TestLogger JUnit" #: Name of the dialect in error messages. 

204 _TESTCASE: ClassVar[Type[Testcase]] = Testcase #: Test case class of this dialect. 

205 _TESTCLASS: ClassVar[Type[Testclass]] = Testclass #: Test class class of this dialect. 

206 _TESTSUITE: ClassVar[Type[Testsuite]] = Testsuite #: Test suite class of this dialect. 

207 

208 def Analyze(self) -> None: 

209 """ 

210 Analyze the XML file, parse the content into an XML data structure and validate the data structure using an XML 

211 schema. 

212 

213 .. hint:: 

214 

215 The time spend for analysis will be made available via property :data:`AnalysisDuration`. 

216 

217 The used XML schema definition is specific to the JunitXml.TestLogger JUnit dialect. 

218 """ 

219 xmlSchemaFile = "TestLogger-JUnit.xsd" 

220 self._Analyze(xmlSchemaFile) 

221 

222 def Write(self, path: Nullable[Path] = None, overwrite: bool = False, regenerate: bool = False) -> None: 

223 """ 

224 Write the data model as XML into a file adhering to the JunitXml.TestLogger JUnit dialect. 

225 

226 :param path: Optional, path to the XML file, if internal path shouldn't be used. 

227 :param overwrite: Optional, if true, overwrite an existing file. 

228 :param regenerate: Optional, if true, regenerate the XML structure from data model. 

229 :raises UnittestError: If the file cannot be overwritten. 

230 :raises UnittestError: If the internal XML data structure wasn't generated. |br| 

231 Call ``Document.Generate()`` or ``Document.Write(..., regenerate=True)``. 

232 :raises UnittestError: If the file cannot be opened or written. 

233 """ 

234 if path is None: 234 ↛ 237line 234 didn't jump to line 237 because the condition on line 234 was always true

235 path = self._path 

236 

237 if not overwrite and path.exists(): 

238 raise UnittestError(f"JUnit XML file '{path}' can not be overwritten.") \ 

239 from FileExistsError(f"File '{path}' already exists.") 

240 

241 if regenerate: 241 ↛ 244line 241 didn't jump to line 244 because the condition on line 241 was always true

242 self.Generate(overwrite=True) 

243 

244 if self._xmlDocument is None: 244 ↛ 245line 244 didn't jump to line 245 because the condition on line 244 was never true

245 ex = UnittestError("Internal XML document tree is empty and needs to be generated before write is possible.") 

246 ex.add_note("Call 'Document.Generate()' or 'Document.Write(..., regenerate=True)'.") 

247 raise ex 

248 

249 content = tostring(self._xmlDocument, encoding="utf-8", xml_declaration=True, pretty_print=True) 

250 try: 

251 with path.open("wb") as file: 

252 file.write(content) 

253 except OSError as ex: 

254 raise UnittestError(f"JUnit XML file '{path}' can not be written.") from ex 

255 

256 def Convert(self) -> None: 

257 """ 

258 Convert the parsed and validated XML data structure into a JUnit test entity hierarchy. 

259 

260 This method converts the root element. As ``<testsuites>`` has no attributes, the summary's start time is the one 

261 of the first test suite: the logger writes the start of the test run into every ``<testsuite>``. 

262 

263 .. hint:: 

264 

265 The time spend for model conversion will be made available via property :data:`ModelConversionDuration`. 

266 

267 :raises UnittestError: If XML was not read and parsed before. |br| 

268 Call ``Document.Analyze()`` or create the document using 

269 ``Document(path, analyzeAndConvert=True)``. 

270 """ 

271 if self._xmlDocument is None: 271 ↛ 272line 271 didn't jump to line 272 because the condition on line 271 was never true

272 ex = UnittestError(f"JUnit XML file '{self._path}' needs to be read and analyzed by an XML parser.") 

273 ex.add_note("Call 'Document.Analyze()' or create the document using 'Document(path, analyzeAndConvert=True)'.") 

274 raise ex 

275 

276 with Stopwatch() as sw: 

277 rootElement: _Element = self._xmlDocument.getroot() 

278 

279 self._name = self._ConvertName(rootElement, optional=True) 

280 

281 for rootNode in rootElement.iterchildren(tag="testsuite"): # type: _Element 

282 self._ConvertTestsuite(self, rootNode) 

283 

284 if len(self._testsuites) > 0: 284 ↛ 287line 284 didn't jump to line 287 because the condition on line 284 was always true

285 self._startTime = firstValue(self._testsuites)._startTime 

286 

287 self.Aggregate() 

288 

289 self._modelConversion = sw.Duration 

290 

291 def _ConvertTestsuite(self, parent: TestsuiteSummary, testsuitesNode: _Element) -> None: 

292 """ 

293 Convert the XML data structure of a ``<testsuite>`` to a test suite. 

294 

295 This method uses private helper methods provided by the base-class. The ``timestamp`` is read as UTC. The 

296 attributes ``id`` (always ``0``) and ``package`` (the same as ``name``) are not read. 

297 

298 :param parent: The test suite summary as a parent element in the test entity hierarchy. 

299 :param testsuitesNode: The current XML element node representing a test suite. 

300 """ 

301 newTestsuite = self._TESTSUITE( 

302 self._ConvertName(testsuitesNode, optional=False), 

303 self._ConvertHostname(testsuitesNode, optional=False), 

304 self._ConvertTimestamp(testsuitesNode, optional=False).replace(tzinfo=timezone.utc), 

305 self._ConvertTime(testsuitesNode, optional=False), 

306 parent=parent 

307 ) 

308 

309 self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite) 

310 

311 def Generate(self, overwrite: bool = False) -> None: 

312 """ 

313 Generate the internal XML data structure from test suites and test cases. 

314 

315 This method generates the XML root element (``<testsuites>``), without attributes, and recursively calls other 

316 generated methods. 

317 

318 :param overwrite: Optional, overwrite the internal XML data structure. 

319 :raises UnittestError: If overwrite is false and the internal XML data structure is not empty. 

320 """ 

321 if not overwrite and self._xmlDocument is not None: 321 ↛ 322line 321 didn't jump to line 322 because the condition on line 321 was never true

322 raise UnittestError("Internal XML document is populated with data.") 

323 

324 rootElement = Element("testsuites") 

325 

326 self._xmlDocument = ElementTree(rootElement) 

327 

328 for testsuite in self._testsuites.values(): 

329 self._GenerateTestsuite(testsuite, rootElement) 

330 

331 def _GenerateTestsuite(self, testsuite: Testsuite, parentElement: _Element) -> None: 

332 """ 

333 Generate the internal XML data structure for a test suite. 

334 

335 This method generates the XML element (``<testsuite>``) and recursively calls other generated methods. Errored 

336 test cases are counted as failures, as the logger knows no errors. The start time is written in UTC. The 

337 attributes ``id`` and ``package`` are written as the logger does: ``0`` and the test suite's name. 

338 

339 :param testsuite: The test suite to convert to an XML data structures. 

340 :param parentElement: The parent XML data structure element, this data structure part will be added to. 

341 :raises UnittestError: If the test suite has no test cases. 

342 :raises UnittestError: If the test suite has no start time. 

343 :raises UnittestError: If the test suite has no duration. 

344 :raises UnittestError: If the test suite has no host name. 

345 """ 

346 if testsuite.TestcaseCount == 0: 

347 raise UnittestError( 

348 f"The {self._DIALECT} format requires test cases in <testsuite>, but '{testsuite._name}' has none." 

349 ) 

350 elif testsuite._startTime is None: 

351 raise UnittestError( 

352 f"The {self._DIALECT} format requires a timestamp on <testsuite>, but '{testsuite._name}' has none." 

353 ) 

354 elif testsuite._duration is None: 354 ↛ 355line 354 didn't jump to line 355 because the condition on line 354 was never true

355 raise UnittestError( 

356 f"The {self._DIALECT} format requires a time on <testsuite>, but '{testsuite._name}' has none." 

357 ) 

358 elif testsuite._hostname is None: 358 ↛ 359line 358 didn't jump to line 359 because the condition on line 358 was never true

359 raise UnittestError( 

360 f"The {self._DIALECT} format requires a hostname on <testsuite>, but '{testsuite._name}' has none." 

361 ) 

362 

363 startTime = testsuite._startTime 

364 if startTime.tzinfo is not None: 

365 startTime = startTime.astimezone(timezone.utc).replace(tzinfo=None) 

366 

367 testsuiteElement = SubElement(parentElement, "testsuite") 

368 testsuiteElement.attrib["name"] = testsuite._name 

369 testsuiteElement.attrib["tests"] = str(testsuite.TestcaseCount) 

370 testsuiteElement.attrib["skipped"] = str(testsuite._skipped) 

371 testsuiteElement.attrib["failures"] = str(testsuite._failed + testsuite._errored) 

372 testsuiteElement.attrib["errors"] = "0" 

373 testsuiteElement.attrib["time"] = f"{testsuite._duration.total_seconds():.6f}" 

374 testsuiteElement.attrib["timestamp"] = startTime.isoformat(timespec="seconds") 

375 testsuiteElement.attrib["hostname"] = testsuite._hostname 

376 testsuiteElement.attrib["id"] = "0" 

377 testsuiteElement.attrib["package"] = testsuite._name 

378 

379 SubElement(testsuiteElement, "properties") 

380 

381 for tc in testsuite._testcases.values(): 

382 self._GenerateTestcase(tc, testsuiteElement) 

383 

384 for testclass in testsuite._testclasses.values(): 

385 for tc in testclass._testcases.values(): 

386 self._GenerateTestcase(tc, testsuiteElement) 

387 

388 def _GenerateTestcase(self, testcase: Testcase, parentElement: _Element) -> None: 

389 """ 

390 Generate the internal XML data structure for a test case. 

391 

392 This method generates the XML element (``<testcase>``) and recursively calls other generated methods. The 

393 duration is written with seven decimals and at least ``0.0000001`` seconds, as the logger does. 

394 

395 :param testcase: The test case to convert to an XML data structures. 

396 :param parentElement: The parent XML data structure element, this data structure part will be added to. 

397 :raises UnittestError: If the test case has no duration. 

398 """ 

399 if testcase._duration is None: 399 ↛ 400line 399 didn't jump to line 400 because the condition on line 399 was never true

400 raise UnittestError( 

401 f"The {self._DIALECT} format requires a time on <testcase>, but '{testcase._name}' has none." 

402 ) 

403 

404 testcaseElement = SubElement(parentElement, "testcase") 

405 testcaseElement.attrib["classname"] = testcase.Classname 

406 testcaseElement.attrib["name"] = testcase._name 

407 testcaseElement.attrib["time"] = f"{max(testcase._duration.total_seconds(), 0.0000001):.7f}" 

408 

409 self._GenerateTestcaseChildren(testcase, testcaseElement) 

410 

411 def _GenerateTestcaseChildren(self, testcase: Testcase, testcaseElement: _Element) -> None: 

412 """ 

413 Generate the child elements of a ``<testcase>`` from the test case's status, message, details and captured output. 

414 

415 A skipped test case gets an empty ``<skipped/>``: its message and details are not written. Every other test case, 

416 which didn't pass, gets a ``<failure type="failure">`` carrying the message (``message`` attribute) and details 

417 (text) - errored ones too. Captured standard output and standard error are written as ``<system-out>`` and 

418 ``<system-err>`` elements. 

419 

420 :param testcase: The test case to convert to XML child elements. 

421 :param testcaseElement: The ``<testcase>`` element, the child elements will be added to. 

422 """ 

423 if testcase._status is TestcaseStatus.Skipped: 

424 SubElement(testcaseElement, "skipped") 

425 elif testcase._status is not TestcaseStatus.Passed: 

426 failureElement = SubElement(testcaseElement, "failure") 

427 failureElement.attrib["type"] = "failure" 

428 

429 if testcase._message is not None: 

430 failureElement.attrib["message"] = testcase._message 

431 

432 if testcase._details is not None: 

433 failureElement.text = testcase._details 

434 

435 if testcase._standardOutput is not None: 

436 SubElement(testcaseElement, "system-out").text = testcase._standardOutput 

437 

438 if testcase._standardError is not None: 

439 SubElement(testcaseElement, "system-err").text = testcase._standardError