Coverage for pyEDAA/Reports/Unittesting/JUnit/Catch2JUnit.py: 90%

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 report written by Catch2's JUnit reporter. 

33 

34.. seealso:: 

35 

36 :ref:`UNITTEST/SpecificDataModel/JUnit/Dialect/Catch2` 

37 |rarr| Differences of the Catch2 JUnit dialect. 

38 :ref:`SCHEMAS/Catch2-JUnit` 

39 |rarr| XML schema of the Catch2 JUnit dialect. 

40""" 

41from __future__ import annotations 

42 

43from datetime import timezone 

44from pathlib import Path 

45from typing import Optional as Nullable, Type, ClassVar 

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, TestsuiteKind, TestcaseStatus, \ 

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 Catch2 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 Catch2 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 Catch2 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 Catch2 JUnit dialect. 

87 

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

89 :returns: Test suite from JUnit specific data model (Catch2 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 juTestsuite._tests = testsuite._tests 

101 juTestsuite._skipped = testsuite._skipped 

102 juTestsuite._errored = testsuite._errored 

103 juTestsuite._failed = testsuite._failed 

104 juTestsuite._passed = testsuite._passed 

105 

106 for tc in testsuite.IterateTestcases(): 

107 ts = tc._parent 

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

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

110 elif ts is testsuite: 

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

112 continue 

113 

114 classname = ts._name 

115 ts = ts._parent 

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

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

118 ts = ts._parent 

119 

120 if classname in juTestsuite._testclasses: 

121 juClass = juTestsuite._testclasses[classname] 

122 else: 

123 juClass = Testclass(classname, parent=juTestsuite) 

124 

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

126 

127 return juTestsuite 

128 

129 

130@export 

131@InheritDocString(ju_TestsuiteSummary, DocStringMergeStrategy.BaseLast) 

132class TestsuiteSummary(ju_TestsuiteSummary): 

133 """ 

134 This is a derived implementation for the Catch2 JUnit dialect. 

135 """ 

136 

137 @classmethod 

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

139 """ 

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

141 summary object adhering to the Catch2 JUnit dialect. 

142 

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

144 :returns: Test suite summary from JUnit specific data model (Catch2 JUnit dialect). 

145 """ 

146 return cls( 

147 testsuiteSummary._name, 

148 startTime=testsuiteSummary._startTime, 

149 duration=testsuiteSummary._totalDuration, 

150 status=testsuiteSummary._status, 

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

152 ) 

153 

154 

155@export 

156class Document(ju_Document): 

157 """ 

158 A document reader and writer for the Catch2 JUnit XML file format. 

159 

160 This class reads, validates and transforms an XML file in the Catch2 JUnit format into a JUnit data model. It can then 

161 be converted into a unified test entity data model. 

162 

163 In reverse, a JUnit data model instance with the specific Catch2 JUnit file format can be created from a unified test 

164 entity data model. This data model can be written as XML into a file. 

165 """ 

166 

167 _DIALECT: ClassVar[str] = "Catch2 + JUnit" #: Name of the dialect in messages. 

168 _TESTCASE: ClassVar[Type[Testcase]] = Testcase #: Class of test cases read by this dialect. 

169 _TESTCLASS: ClassVar[Type[Testclass]] = Testclass #: Class of test classes read by this dialect. 

170 _TESTSUITE: ClassVar[Type[Testsuite]] = Testsuite #: Class of test suites read by this dialect. 

171 

172 def Analyze(self) -> None: 

173 """ 

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

175 schema. 

176 

177 .. hint:: 

178 

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

180 

181 The used XML schema definition is specific to the Catch2 JUnit dialect. 

182 """ 

183 xmlSchemaFile = "Catch2-JUnit.xsd" 

184 self._Analyze(xmlSchemaFile) 

185 

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

187 """ 

188 Write the data model as XML into a file adhering to the Catch2 dialect. 

189 

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

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

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

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

194 :raises UnittestError: If the internal XML data structure wasn't generated. 

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

196 """ 

197 if path is None: 

198 path = self._path 

199 

200 if not overwrite and path.exists(): 

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

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

203 

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

205 self.Generate(overwrite=True) 

206 

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

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

209 ex.add_note("Call 'JUnitDocument.Generate()' or 'JUnitDocument.Write(..., regenerate=True)'.") 

210 raise ex 

211 

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

213 try: 

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

215 file.write(content) 

216 except OSError as ex: 

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

218 

219 def Convert(self) -> None: 

220 """ 

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

222 

223 This method converts the root element. 

224 

225 .. hint:: 

226 

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

228 

229 :raises UnittestError: If XML was not read and parsed before. 

230 """ 

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

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

233 ex.add_note("Call 'JUnitDocument.Analyze()' or create the document using 'JUnitDocument(path, parse=True)'.") 

234 raise ex 

235 

236 with Stopwatch() as sw: 

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

238 

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

240 

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

242 self._ConvertTestsuite(self, rootNode) 

243 

244 self.Aggregate() 

245 

246 self._modelConversion = sw.Duration 

247 

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

249 """ 

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

251 

252 This method uses private helper methods provided by the base-class. 

253 

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

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

256 """ 

257 newTestsuite = Testsuite( 

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

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

260 self._ConvertTimestamp(testsuitesNode, optional=False), 

261 self._ConvertTime(testsuitesNode, optional=True), 

262 parent=parent 

263 ) 

264 

265 self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite) 

266 

267 def _ConvertTestcaseChildren(self, testcaseNode: _Element, newTestcase: Testcase) -> None: 

268 """ 

269 Convert the child elements of a ``<testcase>`` to the test case's status, message, details and captured output. 

270 

271 A test case tagged with ``[!mayfail]`` or ``[!shouldfail]`` failing as expected has a ``<skipped>`` element in front 

272 of its ``<failure>`` or ``<error>`` element. Its status is skipped, its message is the ``<skipped>`` element's 

273 message, its details are the text of the ``<failure>`` or ``<error>`` element. 

274 

275 :param testcaseNode: The current XML element node representing a test case. 

276 :param newTestcase: The test case to update. 

277 :raises UnittestError: If an unknown element is found. 

278 """ 

279 super()._ConvertTestcaseChildren(testcaseNode, newTestcase) 

280 

281 statusNodes = list(testcaseNode.iterchildren("skipped", "failure", "error")) 

282 if len(statusNodes) == 2: 

283 newTestcase._status = TestcaseStatus.Skipped 

284 newTestcase._message = statusNodes[0].attrib.get("message", None) 

285 

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

287 """ 

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

289 

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

291 generated methods. 

292 

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

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

295 :raises UnittestError: If the document has not exactly one test suite. 

296 """ 

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

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

299 

300 if self.TestsuiteCount != 1: 

301 ex = UnittestError(f"The {self._DIALECT} format requires exactly one test suite.") 

302 ex.add_note(f"Found {self.TestsuiteCount} test suites.") 

303 raise ex 

304 

305 rootElement = Element("testsuites") 

306 

307 self._xmlDocument = ElementTree(rootElement) 

308 

309 self._GenerateTestsuite(firstValue(self._testsuites), rootElement) 

310 

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

312 """ 

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

314 

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

316 ``tests``, ``failures``, ``errors`` and ``skipped`` attributes count test cases, an unrecorded hostname is written 

317 as ``tbd``. 

318 

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

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

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

322 """ 

323 if testsuite._startTime is None: 323 ↛ 324line 323 didn't jump to line 324 because the condition on line 323 was never true

324 raise UnittestError(f"The {self._DIALECT} format requires a timestamp on <testsuite>, but the report has none.") 

325 

326 testsuiteElement = SubElement(parentElement, "testsuite") 

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

328 testsuiteElement.attrib["errors"] = str(testsuite._errored) 

329 testsuiteElement.attrib["failures"] = str(testsuite._failed) 

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

331 testsuiteElement.attrib["tests"] = str(testsuite._tests) 

332 testsuiteElement.attrib["hostname"] = "tbd" if testsuite._hostname is None else testsuite._hostname 

333 if testsuite._duration is not None: 333 ↛ 335line 333 didn't jump to line 335 because the condition on line 333 was always true

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

335 testsuiteElement.attrib["timestamp"] = testsuite._startTime.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") 

336 

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

338 self._GenerateTestcase(tc, testsuiteElement) 

339 

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

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

342 self._GenerateTestcase(tc, testsuiteElement) 

343 

344 SubElement(testsuiteElement, "system-out") 

345 SubElement(testsuiteElement, "system-err") 

346 

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

348 """ 

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

350 

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

352 

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

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

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

356 """ 

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

358 raise UnittestError(f"The {self._DIALECT} format requires a time on <testcase>, but the report has none.") 

359 

360 testcaseElement = SubElement(parentElement, "testcase") 

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

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

363 testcaseElement.attrib["time"] = f"{testcase._duration.total_seconds():.3f}" 

364 testcaseElement.attrib["status"] = "run" 

365 

366 self._GenerateTestcaseChildren(testcase, testcaseElement)