ScriptCollection 4.4.2__py3-none-any.whl → 4.4.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. ScriptCollection/Executables.py +1 -1
  2. ScriptCollection/GeneralUtilities.py +13 -1
  3. ScriptCollection/Resources/CultureChooser/CultureChooser.js +0 -0
  4. ScriptCollection/Resources/CultureChooser/index.html +0 -0
  5. ScriptCollection/Resources/Dependencies/JRE/Version.txt +0 -0
  6. ScriptCollection/Resources/Dependencies/OpenAPIGenerator/Version.txt +0 -0
  7. ScriptCollection/Resources/Dependencies/PlantUML/Version.txt +0 -0
  8. ScriptCollection/Resources/Fonts/DejaVuSans-Bold.ttf +0 -0
  9. ScriptCollection/Resources/Fonts/DejaVuSans-BoldOblique.ttf +0 -0
  10. ScriptCollection/Resources/Fonts/DejaVuSans-Oblique.ttf +0 -0
  11. ScriptCollection/Resources/Fonts/DejaVuSans.ttf +0 -0
  12. ScriptCollection/Resources/Fonts/LICENSE.txt +0 -0
  13. ScriptCollection/Resources/MaintenanceSite/MaintenanceSite.html +0 -0
  14. ScriptCollection/SCLog.py +1 -1
  15. ScriptCollection/ScriptCollectionCore.py +117 -11
  16. ScriptCollection/TFCPS/DotNet/TFCPS_CodeUnitSpecific_DotNet.py +1 -1
  17. ScriptCollection/TFCPS/Flutter/TFCPS_CodeUnitSpecific_Flutter.py +1 -1
  18. ScriptCollection/TFCPS/Go/TFCPS_CodeUnitSpecific_Go.py +128 -47
  19. ScriptCollection/TFCPS/Maven/TFCPS_CodeUnitSpecific_Maven.py +139 -7
  20. ScriptCollection/TFCPS/NodeJS/TFCPS_CodeUnitSpecific_NodeJS.py +8 -2
  21. ScriptCollection/TFCPS/Rust/TFCPS_CodeUnitSpecific_Rust.py +169 -7
  22. ScriptCollection/TFCPS/TFCPS_CodeUnit_BuildCodeUnits.py +2 -2
  23. ScriptCollection/TFCPS/TFCPS_Tools_General.py +126 -9
  24. ScriptCollection/TFCPS/TFCPS_VisualRegressionTests.py +446 -0
  25. ScriptCollection/TFCPS/TypeScript/TFCPS_CodeUnitSpecific_TypeScript.py +188 -0
  26. ScriptCollection/TFCPS/TypeScript/__init__.py +0 -0
  27. ScriptCollection/TestKind.py +41 -0
  28. {scriptcollection-4.4.2.dist-info → scriptcollection-4.4.4.dist-info}/METADATA +168 -168
  29. {scriptcollection-4.4.2.dist-info → scriptcollection-4.4.4.dist-info}/RECORD +21 -17
  30. {scriptcollection-4.4.2.dist-info → scriptcollection-4.4.4.dist-info}/WHEEL +0 -0
  31. {scriptcollection-4.4.2.dist-info → scriptcollection-4.4.4.dist-info}/entry_points.txt +0 -0
  32. {scriptcollection-4.4.2.dist-info → scriptcollection-4.4.4.dist-info}/top_level.txt +0 -0
@@ -0,0 +1,446 @@
1
+ import json
2
+ import os
3
+ import re
4
+ import socket
5
+ from PIL import Image, ImageChops
6
+ from ..GeneralUtilities import GeneralUtilities
7
+ from ..ScriptCollectionCore import ScriptCollectionCore
8
+ from .TFCPS_CodeUnitSpecific_Base import TFCPS_CodeUnitSpecific_Base
9
+
10
+
11
+ class TFCPS_VisualRegressionTests:
12
+ """Executes the visual-regression-tests of a codeunit in the playwright-container.
13
+
14
+ The tests are always executed in a container and never directly on the host. Reason: a screenshot depends on
15
+ the operating-system (font-rendering and antialiasing, the available fonts, the rendering of form-controls and
16
+ scrollbars), and the resulting difference is far bigger than the tolerance such a comparison can have. Without
17
+ a defined environment a baseline-screenshot would only be usable on the operating-system it was generated on,
18
+ which would mean one set of baseline-screenshots per operating-system and a pipeline-result which a developer
19
+ can not reproduce.
20
+
21
+ The application under test can be provided in two ways:
22
+ - The playwright-configuration of the codeunit starts it itself (its "webServer"-setting). This is possible
23
+ when the application can be started inside the playwright-container, which is the case for a web-frontend
24
+ whose development-server is started by npm.
25
+ - The caller starts it before calling "run" and passes "application_runs_outside_of_container". This is
26
+ required when the application can not be started inside the playwright-container, for example because it
27
+ needs a runtime which that container does not contain.
28
+
29
+ The used image is defined as "Playwright" in ".ScriptCollection/OCIImages/ImageDefinition.csv" of the
30
+ repository, like the images of all other tools which are used by the build."""
31
+
32
+ __image_name: str = "Playwright"
33
+
34
+ # The image contains the browsers of exactly one playwright-version, so the version of the
35
+ # "@playwright/test"-package of the codeunit has to be the same one. Otherwise playwright would look for
36
+ # browsers which are not contained in the image.
37
+ __tag_pattern_with_version_of_playwright = re.compile(r"^v(?P<version>\d+\.\d+\.\d+)")
38
+
39
+ # The folder the codeunit is mounted to if the tests are started directly on the host.
40
+ __codeunit_folder_in_container: str = "/codeunit"
41
+
42
+ # The folder playwright writes the screenshots of failed testcases to. Playwright empties this folder at the
43
+ # beginning of every run.
44
+ __test_results_folder_relative_path: str = "Other/Artifacts/VisualRegressionTestResults"
45
+
46
+ # The folder the screenshots of failed testcases are preserved in. Both folders are located in
47
+ # "Other/Artifacts", which is ignored by git.
48
+ __failed_testcases_folder_relative_path: str = "Other/Artifacts/VisualRegressionTestFailures"
49
+
50
+ # The name of the environment-variable which tells the testcases under which hostname the application under
51
+ # test is reachable from inside the container. It is only set if the application was started by the caller.
52
+ __environment_variable_name_of_application_host: str = "VisualRegressionTestsApplicationHost"
53
+
54
+ # The folder which contains the baseline-screenshots. Its structure is "<browser>/<platform>/<name>.png",
55
+ # which is the structure the "snapshotPathTemplate" of the playwright-configuration produces.
56
+ __baseline_screenshots_folder_relative_path: str = "Other/Resources/VisualRegressionBaselines"
57
+
58
+ # The folder the testcases write the geometry of the pages to, structured as "<browser>/<platform>/<name>.json".
59
+ # It is located in the artifacts-folder because its content is not a baseline which somebody maintains: it only
60
+ # exists for the comparison inside the run which created it.
61
+ __layouts_folder_relative_path: str = "Other/Artifacts/VisualRegressionLayouts"
62
+
63
+ __tfcps_codeunit: TFCPS_CodeUnitSpecific_Base = None
64
+ __sc: ScriptCollectionCore = None
65
+
66
+ def __init__(self, tfcps_codeunit: TFCPS_CodeUnitSpecific_Base):
67
+ self.__tfcps_codeunit = tfcps_codeunit
68
+ self.__sc = ScriptCollectionCore()
69
+ self.__sc.log.loglevel = tfcps_codeunit.get_verbosity()
70
+
71
+ @GeneralUtilities.check_arguments
72
+ def run(self, update_baselines: bool, playwright_project_folder_relative_path: str = ".", domain_of_externally_started_application: str = None, environment_variables: dict[str, str] = None, playwright_project: str = None) -> None:
73
+ """Executes the visual-regression-tests of the codeunit.
74
+ If 'update_baselines' is true then the baseline-screenshots are regenerated instead of being compared.
75
+ 'playwright_project_folder_relative_path' is the folder inside the codeunit which contains
76
+ "package.json" and "playwright.config.ts"; it allows codeunits which are not implemented in javascript
77
+ to keep these files out of their sourcecode-folder.
78
+ 'domain_of_externally_started_application' has to be set if the caller started the application under test
79
+ instead of letting the playwright-configuration start it (see the documentation of this class). Its value
80
+ is the domain the application is configured for; that domain is made to point to the application inside
81
+ the container and is passed to the testcases as the address they have to use.
82
+ 'environment_variables' are passed to the container, which allows the caller to give the testcases
83
+ values which it defines itself, for example the credentials of a user it created.
84
+ 'playwright_project' restricts the run to one project of the playwright-configuration (which is one
85
+ browser). It is required by codeunits whose testcases change the state of the application under test:
86
+ those have to start the application newly for every browser, because otherwise the second browser would
87
+ find the state which the first one left behind and would therefore see other pages than the first one."""
88
+ codeunit_folder: str = self.__tfcps_codeunit.get_codeunit_folder()
89
+ repository_folder: str = self.__tfcps_codeunit.get_repository_folder()
90
+ playwright_project_folder: str = self.__get_folder_in_codeunit(codeunit_folder, playwright_project_folder_relative_path)
91
+ image: str = self.__tfcps_codeunit.tfcps_Tools_General.oci_image_manager.get_registry_address_for_image_with_default_tag(repository_folder, self.__image_name)
92
+ self.__assert_version_of_playwright_package_matches_image(playwright_project_folder, image)
93
+ self.__assert_docker_daemon_is_reachable()
94
+ image_address, image_tag = ScriptCollectionCore.split_image_address_and_tag(image)
95
+ self.__sc.docker_pull(image_address, image_tag)
96
+ codeunit_folder_in_container: str = self.__get_codeunit_folder_in_container(codeunit_folder)
97
+ working_folder: str = self.__append_relative_path(codeunit_folder_in_container, playwright_project_folder_relative_path)
98
+ # The output-folder is set here and not only in the playwright-configuration of the codeunit, because the
99
+ # screenshots of failed testcases have to be picked up from that folder afterwards. It is passed as an
100
+ # absolute path because the working-folder is not necessarily the codeunit-folder itself.
101
+ output_folder: str = self.__append_relative_path(codeunit_folder_in_container, self.__test_results_folder_relative_path)
102
+ self.__remove_layouts_of_previous_run(codeunit_folder, playwright_project)
103
+ command: str = f"npx playwright test --output={output_folder}"
104
+ if playwright_project is not None:
105
+ command = f"{command} --project={playwright_project}"
106
+ if update_baselines:
107
+ command = f"{command} --update-snapshots"
108
+ # The dependencies are installed inside the container because the "node_modules"-folder of the codeunit can
109
+ # contain packages for another operating-system. "--no-save" is required so that the installation does not
110
+ # modify "package.json" or "package-lock.json".
111
+ command = f"npm install --no-audit --no-fund --no-save && {command}"
112
+ arguments: list[str] = ["run", "--rm"]
113
+ # Playwright recommends this because the default-size of the shared memory of a container is too small for
114
+ # chromium, which makes chromium crash on pages which are not trivial.
115
+ arguments = arguments+["--ipc=host"]
116
+ arguments = arguments+self.__get_mount_arguments(codeunit_folder, codeunit_folder_in_container, playwright_project_folder_relative_path)
117
+ if domain_of_externally_started_application is not None:
118
+ arguments = arguments+self.__get_network_arguments(domain_of_externally_started_application)
119
+ if environment_variables is not None:
120
+ for name, value in environment_variables.items():
121
+ arguments = arguments+["-e", f"{name}={value}"]
122
+ arguments = arguments+["-w", working_folder, image, "/bin/sh", "-c", command]
123
+ result = self.__sc.run_program_argsasarray("docker", arguments, throw_exception_if_exitcode_is_not_zero=False, print_live_output=True, print_errors_as_information=True)
124
+ if result[0] != 0:
125
+ message: str = f"The visual-regression-tests of the codeunit \"{self.__tfcps_codeunit.get_codeunit_name()}\" failed (exit-code {result[0]})."
126
+ folder_with_screenshots: str = self.__preserve_screenshots_of_failed_testcases(codeunit_folder)
127
+ if folder_with_screenshots is None:
128
+ message = f"{message} No screenshots of failed testcases were generated, so probably no testcase was executed at all."
129
+ else:
130
+ message = f"{message} The expected, the actual and the differing screenshot of every failed testcase were stored in \"{folder_with_screenshots}\"."
131
+ message = f"{message} The differences which were found are additionally documented in \"Other/Artifacts/VisualRegressionTestReport\"."
132
+ raise ValueError(message)
133
+
134
+ @GeneralUtilities.check_arguments
135
+ def __remove_layouts_of_previous_run(self, codeunit_folder: str, playwright_project: str) -> None:
136
+ """Removes the layouts which a previous run wrote, so that a page which does not exist anymore is not
137
+ compared any longer.
138
+
139
+ Only the layouts of the browsers which are about to run are removed: a codeunit which executes one browser
140
+ per run would otherwise delete the layouts of the browsers which already ran, and there would never be two
141
+ of them to compare with each other."""
142
+ folder: str = self.__get_folder_in_codeunit(codeunit_folder, self.__layouts_folder_relative_path)
143
+ if playwright_project is not None:
144
+ folder = os.path.join(folder, playwright_project)
145
+ if os.path.isdir(folder):
146
+ GeneralUtilities.ensure_directory_does_not_exist(folder)
147
+
148
+ @GeneralUtilities.check_arguments
149
+ def check_screenshots_are_similar(self, maximal_amount_of_different_pixels: int = 400, downscale_factor: int = 8, maximal_difference_per_color_channel: int = 32, baseline_screenshots_folder_relative_path: str = None) -> None:
150
+ """Asserts that the baseline-screenshots of the browsers are roughly the same picture.
151
+
152
+ The testcases are written once and are executed by every browser, so every page has one baseline-screenshot
153
+ per browser, and each of them is only ever compared with the screenshot of its own browser. A page which
154
+ looks completely different in one browser therefore stays green forever. This check compares the
155
+ baseline-screenshots of the browsers with each other and thereby detects that.
156
+
157
+ It is a coarse check on purpose and it is not the one which detects a misplaced element - use
158
+ 'check_layouts_are_similar' for that. Reason: the engines rasterize text differently, so on a page which
159
+ looks the same thousands of pixels differ, and a threshold which tolerates that is too high to detect a
160
+ part of a page which moved. What this check does detect is a picture which is missing, a page which has a
161
+ different height and a page whose content is completely different.
162
+
163
+ Every screenshot is compared with the screenshot of the same name and the same platform of every other
164
+ browser which has one; a screenshot which only exists for one browser is skipped.
165
+
166
+ 'maximal_amount_of_different_pixels' is the amount of pixels two screenshots are allowed to differ in
167
+ (counted after the downscaling, so it is not the amount of pixels of the original screenshot).
168
+ 'downscale_factor' says by which factor the screenshots are made smaller before they are compared. The
169
+ downscaling averages the pixels of every block, which is what removes the difference of the
170
+ text-rasterization: it is spread over the whole block and stays below the threshold, while a part of the
171
+ page which really moved keeps differing.
172
+ 'maximal_difference_per_color_channel' defines when a pixel counts as different at all.
173
+ 'baseline_screenshots_folder_relative_path' allows a codeunit which stores its baseline-screenshots
174
+ somewhere else to say where they are."""
175
+ codeunit_folder: str = self.__tfcps_codeunit.get_codeunit_folder()
176
+ if baseline_screenshots_folder_relative_path is None:
177
+ baseline_screenshots_folder_relative_path = self.__baseline_screenshots_folder_relative_path
178
+ folder: str = self.__get_folder_in_codeunit(codeunit_folder, baseline_screenshots_folder_relative_path)
179
+ if not os.path.isdir(folder):
180
+ raise ValueError(f"The folder with the baseline-screenshots (\"{folder}\") does not exist. The baseline-screenshots have to be generated before they can be compared with each other.")
181
+ screenshots: dict[tuple[str, str], dict[str, str]] = self.__get_files_per_browser(folder, ".png")
182
+ differences: list[str] = []
183
+ for (platform, name), screenshot_per_browser in sorted(screenshots.items()):
184
+ browsers: list[str] = sorted(screenshot_per_browser.keys())
185
+ for index, browser in enumerate(browsers):
186
+ for other_browser in browsers[index+1:]:
187
+ difference: str = self.__get_difference_of_screenshots(screenshot_per_browser[browser], screenshot_per_browser[other_browser], downscale_factor, maximal_difference_per_color_channel, maximal_amount_of_different_pixels)
188
+ if difference != "":
189
+ differences.append(f"{platform}/{name}: the screenshots of {browser} and {other_browser} {difference}.")
190
+ if 0 < len(differences):
191
+ raise ValueError(f"The browsers do not show the same thing. This means the pages themselves look different in different browsers, which the per-browser-baselines do not detect. Details:{os.linesep}{os.linesep.join(differences)}")
192
+
193
+ @GeneralUtilities.check_arguments
194
+ def check_layouts_are_similar(self, maximal_difference_in_pixels: int = 12, paths_of_elements_to_ignore: list[str] = None) -> None:
195
+ """Asserts that all browsers laid the pages out the same way.
196
+
197
+ This is the check which really answers whether a page looks the same in every browser. Comparing the
198
+ screenshots of the browsers with each other can not answer it: the engines rasterize text differently, so
199
+ even a page which looks identical differs in thousands of pixels, which means the threshold of such a
200
+ comparison has to be so high that it does not detect a shifted part of a page anymore. The geometry of the
201
+ elements does not depend on the rasterization and can therefore be compared directly.
202
+
203
+ Compared is what the testcases wrote down while they ran (see the helper "saveLayoutOfPage" of the
204
+ codeunit): the position and the size of every rendered element of every checked page. Every browser is
205
+ compared with every other browser which checked the same page on the same platform.
206
+
207
+ 'maximal_difference_in_pixels' is how much the position and the size of an element are allowed to differ.
208
+ It is not zero because the engines measure a text slightly differently, so every element whose size comes
209
+ from its own text is a few pixels wider or narrower in one engine than in another; on a headline in a big
210
+ font-size this reaches about ten pixels, which is where the default comes from. A layout-defect (an
211
+ element which lands in the wrong place because an engine treats a css-construct differently) is usually
212
+ far bigger than that.
213
+ 'paths_of_elements_to_ignore' excludes elements whose path contains one of the given texts. This is
214
+ required for parts of a page which are not built by the codeunit itself but by a third-party-library
215
+ which renders a different document in different browsers."""
216
+ codeunit_folder: str = self.__tfcps_codeunit.get_codeunit_folder()
217
+ folder: str = self.__get_folder_in_codeunit(codeunit_folder, self.__layouts_folder_relative_path)
218
+ if not os.path.isdir(folder):
219
+ raise ValueError(f"The folder with the layouts of the pages (\"{folder}\") does not exist. The testcases write it while they run, so either they were not executed or they do not save the layout of the pages they check.")
220
+ if paths_of_elements_to_ignore is None:
221
+ paths_of_elements_to_ignore = []
222
+ layouts: dict[tuple[str, str], dict[str, str]] = self.__get_files_per_browser(folder, ".json")
223
+ differences: list[str] = []
224
+ for (platform, name), file_per_browser in sorted(layouts.items()):
225
+ browsers: list[str] = sorted(file_per_browser.keys())
226
+ for index, browser in enumerate(browsers):
227
+ for other_browser in browsers[index+1:]:
228
+ for difference in self.__get_differences_of_layouts(file_per_browser[browser], file_per_browser[other_browser], maximal_difference_in_pixels, paths_of_elements_to_ignore):
229
+ differences.append(f"{platform}/{name}: {browser} and {other_browser} {difference}")
230
+ if 0 < len(differences):
231
+ amount_which_is_shown: int = 25
232
+ shown: list[str] = differences[:amount_which_is_shown]
233
+ message: str = f"The browsers do not lay the pages out the same way ({len(differences)} difference(s)). This means the pages themselves look different in different browsers, which the comparison of a screenshot with the baseline of its own browser can not detect."
234
+ if len(shown) < len(differences):
235
+ message = f"{message} The first {amount_which_is_shown} differences:"
236
+ raise ValueError(f"{message}{os.linesep}{os.linesep.join(shown)}")
237
+
238
+ @GeneralUtilities.check_arguments
239
+ def __get_differences_of_layouts(self, file: str, other_file: str, maximal_difference_in_pixels: int, paths_of_elements_to_ignore: list[str]) -> list[str]:
240
+ """Returns one description per element which is not at the same place in both given layouts."""
241
+ elements: dict[str, dict] = self.__read_layout(file, paths_of_elements_to_ignore)
242
+ other_elements: dict[str, dict] = self.__read_layout(other_file, paths_of_elements_to_ignore)
243
+ result: list[str] = []
244
+ for path in sorted(set(elements.keys())-set(other_elements.keys())):
245
+ result.append(f"render the element \"{path}\" only in the first one")
246
+ for path in sorted(set(other_elements.keys())-set(elements.keys())):
247
+ result.append(f"render the element \"{path}\" only in the second one")
248
+ for path in sorted(set(elements.keys()) & set(other_elements.keys())):
249
+ element = elements[path]
250
+ other_element = other_elements[path]
251
+ differing_properties: list[str] = []
252
+ for property_name in ["x", "y", "width", "height"]:
253
+ difference: int = abs(element[property_name]-other_element[property_name])
254
+ if maximal_difference_in_pixels < difference:
255
+ differing_properties.append(f"{property_name} {element[property_name]} vs. {other_element[property_name]}")
256
+ if 0 < len(differing_properties):
257
+ result.append(f"place the element \"{path}\" differently ({', '.join(differing_properties)})")
258
+ return result
259
+
260
+ @GeneralUtilities.check_arguments
261
+ def __read_layout(self, file: str, paths_of_elements_to_ignore: list[str]) -> dict[str, dict]:
262
+ with open(file, "r", encoding="utf-8") as file_handle:
263
+ elements: list[dict] = json.load(file_handle)
264
+ return {element["path"]: element for element in elements if not any(ignored in element["path"] for ignored in paths_of_elements_to_ignore)}
265
+
266
+ @GeneralUtilities.check_arguments
267
+ def __get_files_per_browser(self, folder: str, extension: str) -> dict[tuple[str, str], dict[str, str]]:
268
+ """Returns the files of a folder which is structured as "<browser>/<platform>/<name><extension>", grouped
269
+ by the platform and the name they have, so that the files which belong to the same page are together."""
270
+ result: dict[tuple[str, str], dict[str, str]] = {}
271
+ for browser_folder in GeneralUtilities.get_direct_folders_of_folder(folder):
272
+ browser: str = os.path.basename(browser_folder)
273
+ for platform_folder in GeneralUtilities.get_direct_folders_of_folder(browser_folder):
274
+ platform: str = os.path.basename(platform_folder)
275
+ for file in GeneralUtilities.get_direct_files_of_folder(platform_folder):
276
+ if file.lower().endswith(extension):
277
+ key: tuple[str, str] = (platform, os.path.basename(file))
278
+ if key not in result:
279
+ result[key] = {}
280
+ result[key][browser] = file
281
+ return result
282
+
283
+ @GeneralUtilities.check_arguments
284
+ def __get_difference_of_screenshots(self, file: str, other_file: str, downscale_factor: int, maximal_difference_per_color_channel: int, maximal_amount_of_different_pixels: int) -> str:
285
+ """Returns a description of the difference of the two given screenshots, or an empty string when they are
286
+ similar enough."""
287
+ with Image.open(file) as image, Image.open(other_file) as other_image:
288
+ if image.size != other_image.size:
289
+ return f"have different sizes ({image.size[0]}x{image.size[1]} and {other_image.size[0]}x{other_image.size[1]})"
290
+ converted_image: Image.Image = self.__get_downscaled_screenshot(image, downscale_factor)
291
+ converted_other_image: Image.Image = self.__get_downscaled_screenshot(other_image, downscale_factor)
292
+ difference = ImageChops.difference(converted_image, converted_other_image)
293
+ # The difference of a pixel is the biggest difference of its color-channels. The channels are combined
294
+ # with "lighter" (which takes the bigger value of two images) instead of by converting the difference to
295
+ # grayscale, because grayscale weights the channels and would therefore round a small difference which
296
+ # only exists in one channel down to zero.
297
+ red, green, blue = difference.split()
298
+ difference_per_pixel = ImageChops.lighter(ImageChops.lighter(red, green), blue)
299
+ amount_of_different_pixels: int = sum(amount for value, amount in enumerate(difference_per_pixel.histogram()) if maximal_difference_per_color_channel < value)
300
+ if maximal_amount_of_different_pixels < amount_of_different_pixels:
301
+ return f"differ in {amount_of_different_pixels} pixels, which is more than the allowed {maximal_amount_of_different_pixels}"
302
+ return ""
303
+
304
+ @GeneralUtilities.check_arguments
305
+ def __get_downscaled_screenshot(self, image: Image.Image, downscale_factor: int) -> Image.Image:
306
+ # The conversion is required because a comparison needs both pictures to have the same amount of channels,
307
+ # and playwright writes a png with or without an alpha-channel depending on the page.
308
+ converted: Image.Image = image.convert("RGB")
309
+ if downscale_factor < 2:
310
+ return converted
311
+ # "BOX" is the filter which builds the average of every block. Another filter would weight the pixels of a
312
+ # block differently, which would keep more of the difference of the text-rasterization.
313
+ return converted.resize((max(1, converted.width//downscale_factor), max(1, converted.height//downscale_factor)), Image.Resampling.BOX)
314
+
315
+ @GeneralUtilities.check_arguments
316
+ def __get_network_arguments(self, domain_of_application: str) -> list[str]:
317
+ """Returns the arguments which make the application under test, which runs outside of the
318
+ playwright-container, reachable from inside it under the domain it is configured for.
319
+
320
+ The domain is used and not the ip-address, because a server-side-rendered application puts its own
321
+ configured address into the links and form-actions of every page it delivers. A browser which reached it
322
+ under another address would leave the application as soon as it follows one of them."""
323
+ if self.__is_running_in_container():
324
+ # The application was started by this process, which runs in a container, so it listens on the
325
+ # loopback-interface of that container. Sharing its network-namespace is the only way to reach it:
326
+ # its ports are not published to the host, and publishing them would additionally make two parallel
327
+ # builds on the same host collide with each other.
328
+ address_of_application: str = "127.0.0.1"
329
+ result: list[str] = ["--network", f"container:{self.__get_own_container_id()}"]
330
+ else:
331
+ # The application runs directly on the host of the container, which docker makes reachable under the
332
+ # address "host-gateway".
333
+ address_of_application: str = "host-gateway"
334
+ result: list[str] = []
335
+ return result+["--add-host", f"{domain_of_application}:{address_of_application}", "-e", f"{self.__environment_variable_name_of_application_host}={domain_of_application}"]
336
+
337
+ @GeneralUtilities.check_arguments
338
+ def __get_mount_arguments(self, codeunit_folder: str, codeunit_folder_in_container: str, playwright_project_folder_relative_path: str) -> list[str]:
339
+ if self.__is_running_in_container():
340
+ # The build itself runs in a container and uses the docker-daemon of the host. A bind-mount of a path of
341
+ # this container would be resolved by the daemon of the host, where that path does not exist or points to
342
+ # unrelated data. Sharing the own volumes exposes the codeunit to the playwright-container at the same path.
343
+ result: list[str] = ["--volumes-from", self.__get_own_container_id()]
344
+ else:
345
+ result: list[str] = ["-v", f"{codeunit_folder}:{codeunit_folder_in_container}"]
346
+ # The "node_modules"-folder is hidden by an own volume so that the installation inside the container neither
347
+ # uses nor overwrites the packages which were installed outside of the container for another operating-system.
348
+ # The volume is reused by the following runs, so the installation is only slow once.
349
+ volume_name: str = f"{self.__tfcps_codeunit.get_codeunit_name().lower()}-visual-regression-tests-node-modules"
350
+ node_modules_folder: str = self.__append_relative_path(codeunit_folder_in_container, playwright_project_folder_relative_path)+"/node_modules"
351
+ return result+["-v", f"{volume_name}:{node_modules_folder}"]
352
+
353
+ @GeneralUtilities.check_arguments
354
+ def __get_codeunit_folder_in_container(self, codeunit_folder: str) -> str:
355
+ if self.__is_running_in_container():
356
+ # The volumes are shared, so the codeunit is available under the path it has in this container.
357
+ return codeunit_folder.replace("\\", "/")
358
+ return self.__codeunit_folder_in_container
359
+
360
+ @GeneralUtilities.check_arguments
361
+ def __append_relative_path(self, folder_in_container: str, relative_path: str) -> str:
362
+ # The paths inside the container are always posix-paths, independent of the operating-system this process
363
+ # runs on, so they are composed textually and not by "os.path.join".
364
+ normalized_relative_path: str = relative_path.replace("\\", "/").strip("/")
365
+ if normalized_relative_path in ("", "."):
366
+ return folder_in_container
367
+ return f"{folder_in_container}/{normalized_relative_path}"
368
+
369
+ @GeneralUtilities.check_arguments
370
+ def __is_running_in_container(self) -> bool:
371
+ # The filesystem-marker is checked in addition to the convention-based environment-variable because a wrong
372
+ # result here does not only change a message but makes the container access the wrong folder.
373
+ return os.path.exists("/.dockerenv") or self.__sc.is_runnning_in_container()
374
+
375
+ @GeneralUtilities.check_arguments
376
+ def __get_own_container_id(self) -> str:
377
+ # Determines the id of the container this process runs in, so that its volumes can be shared with the
378
+ # playwright-container via "docker run --volumes-from".
379
+ # In mountinfo the own container-id only appears reliably in the source-path of the "/etc/hostname"-,
380
+ # "/etc/hosts"- and "/etc/resolv.conf"-mounts, so the "containers/"-prefix has to be matched explicitly: a
381
+ # plain match of 64 hexadecimal characters would also match overlay-layer-hashes, which are not containers.
382
+ try:
383
+ with open("/proc/self/mountinfo", "r", encoding="utf-8") as file_handle:
384
+ match = re.search(r"/containers/([0-9a-f]{64})/", file_handle.read())
385
+ if match is not None:
386
+ return match.group(1)
387
+ except OSError:
388
+ pass
389
+ # cgroup (v1): the container-id is part of the cgroup-path; here a plain match is safe.
390
+ try:
391
+ with open("/proc/self/cgroup", "r", encoding="utf-8") as file_handle:
392
+ match = re.search(r"[0-9a-f]{64}", file_handle.read())
393
+ if match is not None:
394
+ return match.group(0)
395
+ except OSError:
396
+ pass
397
+ # Fallback: for a container which was started without an explicit hostname the hostname is the short
398
+ # container-id.
399
+ return socket.gethostname()
400
+
401
+ @GeneralUtilities.check_arguments
402
+ def __assert_docker_daemon_is_reachable(self) -> None:
403
+ # Without this check an unreachable daemon would look like a failed testcase, because "docker run" returns a
404
+ # non-zero exit-code in both cases.
405
+ result = self.__sc.run_program_argsasarray("docker", ["version", "--format", "{{.Server.Version}}"], throw_exception_if_exitcode_is_not_zero=False, print_live_output=False)
406
+ if result[0] != 0:
407
+ raise ValueError(f"The visual-regression-tests can not be executed because the docker-daemon is not reachable (exit-code {result[0]}: {result[2].strip()}). The tests are executed via \"docker run\", which requires a running docker-daemon (inside a build-container its socket must be forwarded to the host-daemon). This is an infrastructure-problem and not a failed testcase.")
408
+
409
+ @GeneralUtilities.check_arguments
410
+ def __assert_version_of_playwright_package_matches_image(self, playwright_project_folder: str, image: str) -> None:
411
+ image_tag: str = ScriptCollectionCore.split_image_address_and_tag(image)[1]
412
+ match = self.__tag_pattern_with_version_of_playwright.match(image_tag)
413
+ if match is None:
414
+ raise ValueError(f"The tag \"{image_tag}\" of the image \"{self.__image_name}\" does not contain a playwright-version. Expected is a tag like \"v1.62.1-noble\".")
415
+ version_of_image: str = match.group("version")
416
+ with open(os.path.join(playwright_project_folder, "package.json"), "r", encoding="utf-8") as file_handle:
417
+ version_of_package: str = json.load(file_handle)["devDependencies"]["@playwright/test"]
418
+ if version_of_package != version_of_image:
419
+ raise ValueError(f"The version {version_of_package} of the package \"@playwright/test\" does not match the version {version_of_image} of the image \"{self.__image_name}\" (which is defined in \".ScriptCollection/OCIImages/ImageDefinition.csv\"). The image contains the browsers of exactly one playwright-version, so both have to be updated together.")
420
+
421
+ @GeneralUtilities.check_arguments
422
+ def __preserve_screenshots_of_failed_testcases(self, codeunit_folder: str) -> str:
423
+ """Copies the screenshots of the failed testcases into an own folder and returns that folder,
424
+ or returns None if there are no such screenshots.
425
+ This is required because playwright empties its output-folder at the beginning of every run, so the
426
+ screenshots of a testcase which fails only sporadically would be lost with the next run."""
427
+ source_folder: str = self.__get_folder_in_codeunit(codeunit_folder, self.__test_results_folder_relative_path)
428
+ if not os.path.isdir(source_folder):
429
+ return None
430
+ # Playwright creates one subfolder per failed testcase. The files which are directly in the output-folder
431
+ # (for example ".last-run.json") do not belong to a specific testcase and are therefore not preserved.
432
+ folders_of_failed_testcases: list[str] = GeneralUtilities.get_direct_folders_of_folder(source_folder)
433
+ if len(folders_of_failed_testcases) == 0:
434
+ return None
435
+ timestamp: str = GeneralUtilities.datetime_to_string_for_logfile_name(GeneralUtilities.get_now(), False)
436
+ target_folder: str = os.path.join(self.__get_folder_in_codeunit(codeunit_folder, self.__failed_testcases_folder_relative_path), timestamp)
437
+ GeneralUtilities.ensure_directory_exists(target_folder)
438
+ for folder_of_failed_testcase in folders_of_failed_testcases:
439
+ GeneralUtilities.copy_content_of_folder(folder_of_failed_testcase, os.path.join(target_folder, os.path.basename(folder_of_failed_testcase)))
440
+ return target_folder
441
+
442
+ @GeneralUtilities.check_arguments
443
+ def __get_folder_in_codeunit(self, codeunit_folder: str, relative_path: str) -> str:
444
+ # The relative paths are defined with a slash because they are also passed to the container, so they have to
445
+ # be converted to a path of the operating-system this process runs on.
446
+ return os.path.join(codeunit_folder, *[part for part in relative_path.replace("\\", "/").split("/") if part not in ("", ".")])
@@ -0,0 +1,188 @@
1
+ import os
2
+ import re
3
+ import json
4
+ import shutil
5
+ import requests
6
+ from lxml import etree
7
+ from ...GeneralUtilities import GeneralUtilities, Dependency
8
+ from ...SCLog import LogLevel
9
+ from ..TFCPS_CodeUnitSpecific_Base import TFCPS_CodeUnitSpecific_Base, TFCPS_CodeUnitSpecific_Base_CLI
10
+
11
+ class TFCPS_CodeUnitSpecific_TypeScript_Functions(TFCPS_CodeUnitSpecific_Base):
12
+ """Implements the tasks of a codeunit which contains a plain typescript-project.
13
+
14
+ The typescript-project is expected in "<codeunit>/<codeunit>" and it contains its testcases in the same
15
+ project, because a testcase of a typescript-project belongs next to the file it tests and because the
16
+ compiler has to see the testcases and the sourcecode as one program to be able to check the types of both.
17
+
18
+ This implementation exists next to TFCPS_CodeUnitSpecific_NodeJS: the nodejs-implementation delegates
19
+ every task to a script of the package-file, which means every codeunit has to define the same set of
20
+ scripts itself. This implementation calls the tools directly instead, so a codeunit only has to declare
21
+ the dependencies and the configuration of those tools."""
22
+
23
+ def __init__(self, current_file: str, verbosity: LogLevel, targetenvironmenttype: str, use_cache: bool, is_pre_merge: bool):
24
+ super().__init__(current_file, verbosity, targetenvironmenttype, use_cache, is_pre_merge)
25
+
26
+ @GeneralUtilities.check_arguments
27
+ def get_typescript_project_folder(self) -> str:
28
+ """Returns the folder which contains the package-file of this codeunit."""
29
+ return os.path.join(self.get_codeunit_folder(), self.get_codeunit_name())
30
+
31
+ @GeneralUtilities.check_arguments
32
+ def get_package_json_file(self) -> str:
33
+ return os.path.join(self.get_typescript_project_folder(), "package.json")
34
+
35
+ @GeneralUtilities.check_arguments
36
+ def build(self) -> None:
37
+ # The sourcecode-artifact of a previous run is removed before the build, because it is a copy of the
38
+ # codeunit inside the codeunit. The compiler would otherwise see the copied sourcecode as part of the
39
+ # program and would report every declaration of it as a duplicate.
40
+ GeneralUtilities.ensure_directory_does_not_exist(os.path.join(self.get_artifacts_folder(), "SourceCode"))
41
+ build_output_folder = os.path.join(self.get_typescript_project_folder(), "dist")
42
+ GeneralUtilities.ensure_directory_does_not_exist(build_output_folder)
43
+ self.__run_npx("tsc --project tsconfig.json")
44
+ GeneralUtilities.assert_condition(os.path.isdir(build_output_folder), f'The compilation did not produce an output in "{build_output_folder}".')
45
+ target_folder = os.path.join(self.get_artifacts_folder(), "BuildResult_TypeScript")
46
+ GeneralUtilities.ensure_directory_does_not_exist(target_folder)
47
+ shutil.copytree(build_output_folder, target_folder)
48
+ self.__generate_bom_for_typescript_project()
49
+ self.copy_source_files_to_output_directory()
50
+
51
+ @GeneralUtilities.check_arguments
52
+ def __generate_bom_for_typescript_project(self) -> None:
53
+ codeunit_version = self.tfcps_Tools_General.get_version_of_codeunit(self.get_codeunit_file())
54
+ bom_folder = os.path.join(self.get_artifacts_folder(), "BOM")
55
+ GeneralUtilities.ensure_directory_exists(bom_folder)
56
+ target_bom_file = os.path.join(bom_folder, f"{self.get_codeunit_name()}.{codeunit_version}.bom.xml")
57
+ # The output-file is passed as a path which is relative to the project-folder, because cyclonedx-npm
58
+ # resolves it against its working-directory.
59
+ relative_target_bom_file = os.path.relpath(target_bom_file, self.get_typescript_project_folder()).replace("\\", "/")
60
+ self.__run_npx(f"@cyclonedx/cyclonedx-npm --output-format xml --output-file {relative_target_bom_file}")
61
+ GeneralUtilities.assert_file_exists(target_bom_file)
62
+ self._protected_sc.format_xml_file(target_bom_file)
63
+
64
+ @GeneralUtilities.check_arguments
65
+ def linting(self) -> None:
66
+ codeunit_folder = self.get_codeunit_folder()
67
+ self._protected_sc.normalize_invisible_characters_of_files_in_folder(codeunit_folder, ["ts", "js", "json"])
68
+ # "--max-warnings 0" makes a warning fail the linting as well, because a warning is a linting-issue too.
69
+ self.__run_npx("eslint . --max-warnings 0")
70
+
71
+ @GeneralUtilities.check_arguments
72
+ def do_common_tasks(self, current_codeunit_version: str) -> None:
73
+ self.do_common_tasks_base(current_codeunit_version)
74
+ self.tfcps_Tools_General.replace_version_in_packagejson_file(self.get_package_json_file(), current_codeunit_version)
75
+ self.tfcps_Tools_General.do_npm_install(self.get_typescript_project_folder(), True, self.use_cache())
76
+
77
+ @GeneralUtilities.check_arguments
78
+ def generate_reference(self) -> None:
79
+ # docfx can not extract a class-reference from typescript-sourcecode, so only the articles of the
80
+ # reference-content are generated.
81
+ self.generate_reference_using_docfx()
82
+
83
+ @GeneralUtilities.check_arguments
84
+ def run_testcases(self) -> None:
85
+ codeunit_name = self.get_codeunit_name()
86
+ coverage_folder = os.path.join(self.get_artifacts_folder(), "TestCoverage")
87
+ GeneralUtilities.ensure_directory_exists(coverage_folder)
88
+ coverage_file = os.path.join(coverage_folder, "TestCoverage.xml")
89
+ GeneralUtilities.ensure_file_does_not_exist(coverage_file)
90
+ generated_coverage_file = os.path.join(self.get_typescript_project_folder(), "coverage", "cobertura-coverage.xml")
91
+ GeneralUtilities.ensure_file_does_not_exist(generated_coverage_file)
92
+ self.__run_npx("jest --coverage --coverageReporters=cobertura")
93
+ GeneralUtilities.assert_file_exists(generated_coverage_file)
94
+ shutil.move(generated_coverage_file, coverage_file)
95
+ self.__normalize_coverage_file(coverage_file)
96
+ self.run_testcases_common_post_task(self.get_repository_folder(), codeunit_name, True, self.get_target_environment_type())
97
+
98
+ @GeneralUtilities.check_arguments
99
+ def __normalize_coverage_file(self, coverage_file: str) -> None:
100
+ """Makes the coverage-report which jest wrote match the expectations of the further processing: it must
101
+ contain exactly one package which is named like the codeunit, and the filename of a class must be
102
+ relative to the codeunit-folder, while jest writes it relative to the project-folder."""
103
+ codeunit_name = self.get_codeunit_name()
104
+ tree = etree.parse(coverage_file)
105
+ root = tree.getroot()
106
+ for package in root.findall(".//package"):
107
+ package.set("name", codeunit_name)
108
+ for class_element in root.findall(".//class"):
109
+ filename = class_element.get("filename")
110
+ if filename is not None:
111
+ filename_with_slashes = filename.replace("\\", "/")
112
+ class_element.set("filename", f"{codeunit_name}/{filename_with_slashes}")
113
+ class_element.set("name", os.path.basename(filename_with_slashes))
114
+ tree.write(coverage_file, pretty_print=True, xml_declaration=True, encoding="UTF-8")
115
+ self.tfcps_Tools_General.merge_packages(coverage_file, codeunit_name)
116
+
117
+ @GeneralUtilities.check_arguments
118
+ def __run_npx(self, arguments: str) -> None:
119
+ # The tools are run through npx instead of through a script of the package-file, so that a codeunit does
120
+ # not have to define a script for every task. "--no-install" makes npx fail instead of downloading a tool
121
+ # which the package-file does not declare, because a build must not depend on what npx finds online.
122
+ self._protected_sc.run_with_epew("npx", f"--no-install {arguments}", self.get_typescript_project_folder(), print_live_output=self.get_verbosity() == LogLevel.Debug, encode_argument_in_base64=True)
123
+
124
+ @GeneralUtilities.check_arguments
125
+ def get_dependencies(self) -> dict[str, set[str]]:
126
+ return GeneralUtilities.merge_dependency_lists([self.__get_dependencies_from_package_json_file()])
127
+
128
+ @GeneralUtilities.check_arguments
129
+ def __get_dependencies_from_package_json_file(self) -> list[Dependency]:
130
+ result: list[Dependency] = []
131
+ for name, dependency_version in self.__enumerate_dependency_entries():
132
+ result.append(Dependency(name, dependency_version))
133
+ return result
134
+
135
+ @GeneralUtilities.check_arguments
136
+ def __enumerate_dependency_entries(self) -> list[tuple[str, str]]:
137
+ """Returns the dependencies of the package-file as tuples of their name and their version. Only a
138
+ dependency whose version is a plain version-number is returned, because a dependency which points to a
139
+ file, a repository or a tag has no version which could be updated."""
140
+ content = json.loads(GeneralUtilities.read_text_from_file(self.get_package_json_file()))
141
+ result: list[tuple[str, str]] = []
142
+ for section in ("dependencies", "devDependencies"):
143
+ for name, declared_version in content.get(section, {}).items():
144
+ # A declared version usually carries a range-prefix ("^1.2.3" or "~1.2.3"), which is not part of
145
+ # the version itself.
146
+ version_without_prefix = declared_version.lstrip("^~")
147
+ if re.match(r"^\d+\.\d+\.\d+$", version_without_prefix) is not None:
148
+ result.append((name, version_without_prefix))
149
+ return result
150
+
151
+ @GeneralUtilities.check_arguments
152
+ def get_available_versions(self, dependencyname: str) -> list[str]:
153
+ # The registry of npm answers with all published versions of a package.
154
+ response = requests.get(f"https://registry.npmjs.org/{dependencyname}", headers={"Accept": "application/vnd.npm.install-v1+json"}, timeout=60)
155
+ response.raise_for_status()
156
+ result: list[str] = []
157
+ for version_string in response.json().get("versions", {}).keys():
158
+ if re.match(r"^\d+\.\d+\.\d+$", version_string) is not None:
159
+ result.append(version_string)
160
+ return result
161
+
162
+ @GeneralUtilities.check_arguments
163
+ def set_dependency_version(self, name: str, new_version: str) -> None:
164
+ package_json_file = self.get_package_json_file()
165
+ content = json.loads(GeneralUtilities.read_text_from_file(package_json_file))
166
+ dependency_was_set: bool = False
167
+ for section in ("dependencies", "devDependencies"):
168
+ if name in content.get(section, {}):
169
+ # The range-prefix of the former declaration is kept, because it states how the project wants to
170
+ # accept updates and that is not a decision of this function.
171
+ former_declaration = content[section][name]
172
+ prefix = former_declaration[0] if former_declaration[0] in ("^", "~") else GeneralUtilities.empty_string
173
+ content[section][name] = f"{prefix}{new_version}"
174
+ dependency_was_set = True
175
+ GeneralUtilities.assert_condition(dependency_was_set, f'The package-file "{package_json_file}" does not contain a dependency which is named "{name}".')
176
+ GeneralUtilities.write_text_to_file(package_json_file, json.dumps(content, indent=2, ensure_ascii=False) + "\n")
177
+ self._protected_sc.format_json_file(package_json_file)
178
+
179
+ class TFCPS_CodeUnitSpecific_TypeScript_CLI:
180
+
181
+ @staticmethod
182
+ @GeneralUtilities.check_arguments
183
+ def parse(file: str) -> TFCPS_CodeUnitSpecific_TypeScript_Functions:
184
+ parser = TFCPS_CodeUnitSpecific_Base_CLI.get_base_parser()
185
+ #add custom parameter if desired
186
+ args = parser.parse_args()
187
+ result: TFCPS_CodeUnitSpecific_TypeScript_Functions = TFCPS_CodeUnitSpecific_TypeScript_Functions(file, LogLevel(int(args.verbosity)), args.targetenvironmenttype, not args.nocache, args.ispremerge)
188
+ return result
File without changes