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

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 

53from pyEDAA.Reports.Unittesting import TestsuiteSummary as ut_TestsuiteSummary, Testsuite as ut_Testsuite 

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

55from pyEDAA.Reports.Unittesting.JUnit import Testsuite as ju_Testsuite, TestsuiteSummary as ju_TestsuiteSummary 

56from pyEDAA.Reports.Unittesting.JUnit import 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 

111 classname = ts._name 

112 ts = ts._parent 

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

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

115 ts = ts._parent 

116 

117 if classname in juTestsuite._testclasses: 

118 juClass = juTestsuite._testclasses[classname] 

119 else: 

120 juClass = Testclass(classname, parent=juTestsuite) 

121 

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

123 

124 return juTestsuite 

125 

126 

127@export 

128@InheritDocString(ju_TestsuiteSummary, DocStringMergeStrategy.BaseLast) 

129class TestsuiteSummary(ju_TestsuiteSummary): 

130 """ 

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

132 """ 

133 

134 @classmethod 

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

136 """ 

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

138 summary object adhering to the Catch2 JUnit dialect. 

139 

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

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

142 """ 

143 return cls( 

144 testsuiteSummary._name, 

145 startTime=testsuiteSummary._startTime, 

146 duration=testsuiteSummary._totalDuration, 

147 status=testsuiteSummary._status, 

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

149 ) 

150 

151 

152@export 

153class Document(ju_Document): 

154 """ 

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

156 

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

158 be converted into a unified test entity data model. 

159 

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

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

162 """ 

163 

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

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

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

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

168 

169 def Analyze(self) -> None: 

170 """ 

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

172 schema. 

173 

174 .. hint:: 

175 

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

177 

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

179 """ 

180 xmlSchemaFile = "Catch2-JUnit.xsd" 

181 self._Analyze(xmlSchemaFile) 

182 

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

184 """ 

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

186 

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

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

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

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

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

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

193 """ 

194 if path is None: 

195 path = self._path 

196 

197 if not overwrite and path.exists(): 

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

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

200 

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

202 self.Generate(overwrite=True) 

203 

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

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

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

207 raise ex 

208 

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

210 try: 

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

212 file.write(content) 

213 except OSError as ex: 

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

215 

216 def Convert(self) -> None: 

217 """ 

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

219 

220 This method converts the root element. 

221 

222 .. hint:: 

223 

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

225 

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

227 """ 

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

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

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

231 raise ex 

232 

233 with Stopwatch() as sw: 

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

235 

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

237 

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

239 self._ConvertTestsuite(self, rootNode) 

240 

241 self.Aggregate() 

242 

243 self._modelConversion = sw.Duration 

244 

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

246 """ 

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

248 

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

250 

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

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

253 """ 

254 newTestsuite = Testsuite( 

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

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

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

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

259 parent=parent 

260 ) 

261 

262 self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite) 

263 

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

265 """ 

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

267 

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

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

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

271 

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

273 :param newTestcase: The test case to update. 

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

275 """ 

276 super()._ConvertTestcaseChildren(testcaseNode, newTestcase) 

277 

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

279 if len(statusNodes) == 2: 

280 newTestcase._status = TestcaseStatus.Skipped 

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

282 

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

284 """ 

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

286 

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

288 generated methods. 

289 

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

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

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

293 """ 

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

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

296 

297 if self.TestsuiteCount != 1: 

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

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

300 raise ex 

301 

302 rootElement = Element("testsuites") 

303 

304 self._xmlDocument = ElementTree(rootElement) 

305 

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

307 

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

309 """ 

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

311 

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

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

314 as ``tbd``. 

315 

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

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

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

319 """ 

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

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

322 

323 testsuiteElement = SubElement(parentElement, "testsuite") 

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

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

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

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

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

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

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

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

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

333 

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

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

336 self._GenerateTestcase(tc, testsuiteElement) 

337 

338 SubElement(testsuiteElement, "system-out") 

339 SubElement(testsuiteElement, "system-err") 

340 

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

342 """ 

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

344 

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

346 

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

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

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

350 """ 

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

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

353 

354 testcaseElement = SubElement(parentElement, "testcase") 

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

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

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

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

359 

360 self._GenerateTestcaseChildren(testcase, testcaseElement)