Coverage for pyEDAA/Reports/Unittesting/JUnit/CTestJUnit.py: 84%

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

2# _____ ____ _ _ ____ _ # 

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

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

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

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

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

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

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

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

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

15# Copyright 2023-2023 Patrick Lehmann - Bötzingen, Germany # 

16# # 

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

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

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

20# # 

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

22# # 

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

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

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

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

27# limitations under the License. # 

28# # 

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

30# ==================================================================================================================== # 

31# 

32""" 

33Reader for JUnit unit testing summary files in XML format. 

34""" 

35from pathlib import Path 

36from time import perf_counter_ns 

37from typing import Optional as Nullable, Generator, Tuple, Union, TypeVar, Type, ClassVar 

38 

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

40from pyTooling.Common import firstValue 

41from pyTooling.Decorators import export, InheritDocString 

42 

43from pyEDAA.Reports.Unittesting import UnittestException, TestsuiteKind 

44from pyEDAA.Reports.Unittesting import TestcaseStatus, TestsuiteStatus, IterationScheme 

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

46from pyEDAA.Reports.Unittesting.JUnit import Testcase as ju_Testcase, Testclass as ju_Testclass, Testsuite as ju_Testsuite 

47from pyEDAA.Reports.Unittesting.JUnit import TestsuiteSummary as ju_TestsuiteSummary, Document as ju_Document 

48 

49 

50TestsuiteType = TypeVar("TestsuiteType", bound="Testsuite") 

51TestcaseAggregateReturnType = Tuple[int, int, int] 

52TestsuiteAggregateReturnType = Tuple[int, int, int, int, int] 

53 

54 

55@export 

56@InheritDocString(ju_Testcase, merge=True) 

57class Testcase(ju_Testcase): 

58 """ 

59 This is a derived implementation for the CTest JUnit dialect. 

60 """ 

61 

62 

63@export 

64@InheritDocString(ju_Testclass, merge=True) 

65class Testclass(ju_Testclass): 

66 """ 

67 This is a derived implementation for the CTest JUnit dialect. 

68 """ 

69 

70 

71@export 

72@InheritDocString(ju_Testsuite, merge=True) 

73class Testsuite(ju_Testsuite): 

74 """ 

75 This is a derived implementation for the CTest JUnit dialect. 

76 """ 

77 

78 @classmethod 

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

80 """ 

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

82 adhering to the CTest JUnit dialect. 

83 

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

85 :returns: Test suite from JUnit specific data model (CTest JUnit dialect). 

86 """ 

87 juTestsuite = cls( 

88 testsuite._name, 

89 hostname=testsuite._hostname, 

90 startTime=testsuite._startTime, 

91 duration=testsuite._totalDuration, 

92 status= testsuite._status, 

93 ) 

94 

95 juTestsuite._tests = testsuite._tests 

96 juTestsuite._skipped = testsuite._skipped 

97 juTestsuite._errored = testsuite._errored 

98 juTestsuite._failed = testsuite._failed 

99 juTestsuite._passed = testsuite._passed 

100 

101 for tc in testsuite.IterateTestcases(): 

102 ts = tc._parent 

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

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

105 

106 classname = ts._name 

107 ts = ts._parent 

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

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

110 ts = ts._parent 

111 

112 if classname in juTestsuite._testclasses: 

113 juClass = juTestsuite._testclasses[classname] 

114 else: 

115 juClass = Testclass(classname, parent=juTestsuite) 

116 

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

118 

119 return juTestsuite 

120 

121 

122@export 

123@InheritDocString(ju_TestsuiteSummary, merge=True) 

124class TestsuiteSummary(ju_TestsuiteSummary): 

125 """ 

126 This is a derived implementation for the CTest JUnit dialect. 

127 """ 

128 

129 @classmethod 

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

131 """ 

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

133 summary object adhering to the CTest JUnit dialect. 

134 

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

136 :returns: Test suite summary from JUnit specific data model (CTest JUnit dialect). 

137 """ 

138 return cls( 

139 testsuiteSummary._name, 

140 startTime=testsuiteSummary._startTime, 

141 duration=testsuiteSummary._totalDuration, 

142 status=testsuiteSummary._status, 

143 testsuites=(ut_Testsuite.FromTestsuite(testsuite) for testsuite in testsuiteSummary._testsuites.values()) 

144 ) 

145 

146 

147@export 

148class Document(ju_Document): 

149 """ 

150 A document reader and writer for the CTest JUnit XML file format. 

151 

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

153 be converted into a unified test entity data model. 

154 

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

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

157 """ 

158 

159 _DIALECT: ClassVar[str] = "CTest + JUnit" 

160 _TESTCASE: ClassVar[Type[Testcase]] = Testcase 

161 _TESTCLASS: ClassVar[Type[Testclass]] = Testclass 

162 _TESTSUITE: ClassVar[Type[Testsuite]] = Testsuite 

163 

164 @classmethod 

165 def FromTestsuiteSummary(cls, xmlReportFile: Path, testsuiteSummary: ut_TestsuiteSummary): 

166 doc = cls(xmlReportFile) 

167 doc._name = testsuiteSummary._name 

168 doc._startTime = testsuiteSummary._startTime 

169 doc._duration = testsuiteSummary._totalDuration 

170 doc._status = testsuiteSummary._status 

171 doc._tests = testsuiteSummary._tests 

172 doc._skipped = testsuiteSummary._skipped 

173 doc._errored = testsuiteSummary._errored 

174 doc._failed = testsuiteSummary._failed 

175 doc._passed = testsuiteSummary._passed 

176 

177 doc.AddTestsuites(Testsuite.FromTestsuite(testsuite) for testsuite in testsuiteSummary._testsuites.values()) 

178 

179 return doc 

180 

181 def Analyze(self) -> None: 

182 """ 

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

184 schema. 

185 

186 .. hint:: 

187 

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

189 

190 The used XML schema definition is specific to the CTest JUnit dialect. 

191 """ 

192 xmlSchemaFile = "CTest-JUnit.xsd" 

193 self._Analyze(xmlSchemaFile) 

194 

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

196 """ 

197 Write the data model as XML into a file adhering to the CTest dialect. 

198 

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

200 :param overwrite: If true, overwrite an existing file. 

201 :param regenerate: If true, regenerate the XML structure from data model. 

202 :raises UnittestException: If the file cannot be overwritten. 

203 :raises UnittestException: If the internal XML data structure wasn't generated. 

204 :raises UnittestException: If the file cannot be opened or written. 

205 """ 

206 if path is None: 

207 path = self._path 

208 

209 if not overwrite and path.exists(): 209 ↛ 210line 209 didn't jump to line 210 because the condition on line 209 was never true

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

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

212 

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

214 self.Generate(overwrite=True) 

215 

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

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

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

219 raise ex 

220 

221 try: 

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

223 file.write(tostring(self._xmlDocument, encoding="utf-8", xml_declaration=True, pretty_print=True)) 

224 except Exception as ex: 

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

226 

227 def Convert(self) -> None: 

228 """ 

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

230 

231 This method converts the root element. 

232 

233 .. hint:: 

234 

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

236 

237 :raises UnittestException: If XML was not read and parsed before. 

238 """ 

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

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

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

242 raise ex 

243 

244 startConversion = perf_counter_ns() 

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

246 

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

248 self._startTime =self._ConvertTimestamp(rootElement, optional=True) 

249 self._duration = self._ConvertTime(rootElement, optional=True) 

250 

251 # tests = rootElement.getAttribute("tests") 

252 # skipped = rootElement.getAttribute("skipped") 

253 # errors = rootElement.getAttribute("errors") 

254 # failures = rootElement.getAttribute("failures") 

255 # assertions = rootElement.getAttribute("assertions") 

256 

257 hostname = self._ConvertHostname(rootElement, optional=True, default=None) 

258 ts = Testsuite(self._name, hostname, startTime=self._startTime, duration=self._duration, parent=self) 

259 self._ConvertTestsuiteChildren(rootElement, ts) 

260 

261 self.Aggregate() 

262 endConversation = perf_counter_ns() 

263 self._modelConversion = (endConversation - startConversion) / 1e9 

264 

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

266 """ 

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

268 

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

270 

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

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

273 """ 

274 newTestsuite = Testsuite( 

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

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

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

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

279 parent=parent 

280 ) 

281 

282 self._ConvertTestsuiteChildren(testsuitesNode, newTestsuite) 

283 

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

285 """ 

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

287 

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

289 

290 :param overwrite: Overwrite the internal XML data structure. 

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

292 """ 

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

294 raise UnittestException(f"Internal XML document is populated with data.") 

295 

296 if self.TestsuiteCount != 1: 

297 ex = UnittestException(f"The CTest JUnit format requires exactly one test suite.") 

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

299 raise ex 

300 

301 testsuite = firstValue(self._testsuites) 

302 

303 rootElement = Element("testsuite") 

304 rootElement.attrib["name"] = self._name 

305 if self._startTime is None: 

306 raise UnittestException( 

307 f"The {self._DIALECT} format requires a timestamp on <testsuite>, but the report has none." 

308 ) 

309 rootElement.attrib["timestamp"] = f"{self._startTime.isoformat()}" 

310 if self._duration is not None: 

311 rootElement.attrib["time"] = f"{self._duration.total_seconds():.6f}" 

312 rootElement.attrib["tests"] = str(self._tests) 

313 rootElement.attrib["failures"] = str(self._failed) 

314 # rootElement.attrib["errors"] = str(self._errored) 

315 rootElement.attrib["skipped"] = str(self._skipped) 

316 rootElement.attrib["disabled"] = "0" # TODO: find a value 

317 # if self._assertionCount is not None: 

318 # rootElement.attrib["assertions"] = f"{self._assertionCount}" 

319 # CTest-JUnit.xsd requires 'hostname', so an unrecorded host is named as unknown. 

320 rootElement.attrib["hostname"] = testsuite._hostname if testsuite._hostname is not None else "unknownhost" 

321 

322 self._xmlDocument = ElementTree(rootElement) 

323 

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

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

326 self._GenerateTestcase(tc, rootElement) 

327 

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

329 """ 

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

331 

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

333 

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

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

336 """ 

337 testcaseElement = SubElement(parentElement, "testcase") 

338 if testcase.Classname is not None: 338 ↛ 340line 338 didn't jump to line 340 because the condition on line 338 was always true

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

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

341 if testcase._duration is not None: 341 ↛ 343line 341 didn't jump to line 343 because the condition on line 341 was always true

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

343 if testcase._assertionCount is not None: 343 ↛ 344line 343 didn't jump to line 344 because the condition on line 343 was never true

344 testcaseElement.attrib["assertions"] = f"{testcase._assertionCount}" 

345 

346 testcaseElement.attrib["status"] = "run" # TODO: find a value 

347 

348 if testcase._status is TestcaseStatus.Passed: 

349 pass 

350 elif testcase._status is TestcaseStatus.Failed: 350 ↛ 352line 350 didn't jump to line 352 because the condition on line 350 was always true

351 failureElement = SubElement(testcaseElement, "failure") 

352 elif testcase._status is TestcaseStatus.Skipped: 

353 skippedElement = SubElement(testcaseElement, "skipped") 

354 else: 

355 errorElement = SubElement(testcaseElement, "error")