robotframework-plugins 2026.11.0.dev1__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 (195) hide show
  1. robotframework_plugins/__init__.py +14 -0
  2. robotframework_plugins/_assets/catalog.json +143 -0
  3. robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
  4. robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
  5. robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
  6. robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
  7. robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
  8. robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
  9. robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
  10. robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
  11. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +110 -0
  12. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
  13. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
  14. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
  15. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
  16. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  31. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  32. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
  33. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  34. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
  35. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  36. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  37. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  38. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
  39. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  40. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  41. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  42. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  50. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  51. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  52. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  108. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
  109. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  110. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  115. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  116. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
  117. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  128. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  129. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  130. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  143. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  144. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  145. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  146. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  147. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
  148. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  149. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  172. robotframework_plugins/_assets.py +120 -0
  173. robotframework_plugins/_catalog.py +123 -0
  174. robotframework_plugins/_snapshot.py +230 -0
  175. robotframework_plugins/adapters/__init__.py +53 -0
  176. robotframework_plugins/adapters/_base.py +400 -0
  177. robotframework_plugins/adapters/claude_code.py +312 -0
  178. robotframework_plugins/adapters/claude_desktop.py +129 -0
  179. robotframework_plugins/adapters/codex.py +276 -0
  180. robotframework_plugins/adapters/copilot.py +87 -0
  181. robotframework_plugins/adapters/cursor.py +295 -0
  182. robotframework_plugins/adapters/goose.py +240 -0
  183. robotframework_plugins/adapters/opencode.py +170 -0
  184. robotframework_plugins/bundle.py +85 -0
  185. robotframework_plugins/cli.py +1311 -0
  186. robotframework_plugins/detect.py +121 -0
  187. robotframework_plugins/manifest.py +338 -0
  188. robotframework_plugins/py.typed +0 -0
  189. robotframework_plugins/skillzip.py +39 -0
  190. robotframework_plugins/transforms.py +725 -0
  191. robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
  192. robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
  193. robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
  194. robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
  195. robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,122 @@
1
+ # Troubleshooting
2
+
3
+ - Element not found
4
+ - ElementNotInteractableException or ElementClickInterceptedException
5
+ - StaleElementReferenceException
6
+ - Wait Until keyword times out although the element is there
7
+ - UnexpectedAlertPresentException
8
+ - Unsupported browser name
9
+ - SessionNotCreatedException
10
+ - Chrome fails to start in CI or a container
11
+ - Clicks have no effect after a login
12
+ - Screenshots, page source and logs
13
+
14
+ ## Element not found
15
+
16
+ `Element with locator '…' not found.`
17
+
18
+ | Cause | Fix |
19
+ |---|---|
20
+ | The element appears after page load or an AJAX call | Add `Wait Until Element Is Visible` / `Wait Until Page Contains Element` before the step |
21
+ | The element is inside an iframe | `Select Frame` first; `Unselect Frame` afterwards |
22
+ | A previous `Select Frame` (or `Page Should Contain`, which resets to the main document) left the wrong frame selected | Select the right frame again |
23
+ | The element opened in a new window or tab | `Switch Window NEW` |
24
+ | A locator without a prefix is text, not an id or name | Use `link:`, `xpath://*[normalize-space()="…"]` or `css:` |
25
+
26
+ ## ElementNotInteractableException or ElementClickInterceptedException
27
+
28
+ `element not interactable` / `element click intercepted: Element … is not clickable at point (x, y). Other element would receive the click`
29
+
30
+ | Cause | Fix |
31
+ |---|---|
32
+ | Overlay, spinner, cookie banner or modal covers the element | `Wait Until Element Is Not Visible` on the overlay, or close the banner |
33
+ | Element is outside the viewport or a small headless window | `Scroll Element Into View`, or `options=add_argument("--window-size=1920,1080")` |
34
+ | Element exists but is hidden or disabled | `Wait Until Element Is Visible` / `Wait Until Element Is Enabled` |
35
+ | Animation still running | Wait for the final state (a class or text), not with `Sleep` |
36
+
37
+ A JavaScript click (`Execute Javascript arguments[0].click(); ARGUMENTS ${element}`) hides the real problem from the test; use it only when the UI is known to behave correctly for users.
38
+
39
+ ## StaleElementReferenceException
40
+
41
+ `stale element reference: stale element not found`
42
+
43
+ A WebElement stored in a variable (`Get WebElement`, `Get WebElements`, JavaScript return values) belongs to a DOM node that the page has since replaced. Pass the locator string instead and let each keyword look the element up again; the `Wait Until …` keywords already retry on stale elements.
44
+
45
+ ## Wait Until keyword times out although the element is there
46
+
47
+ | Cause | Fix |
48
+ |---|---|
49
+ | `Wait Until Element Is Visible` on an element with `display:none` or `visibility:hidden` | Wait for what the user sees, or use `Wait Until Page Contains Element` for presence |
50
+ | The locator matches a hidden duplicate first (mobile and desktop menus) | Make the locator unique, e.g. scope it with `css:#desktop-nav …` |
51
+ | The element is in an iframe | `Select Frame` before the wait |
52
+ | Timeout too short for CI | Raise the import `timeout`, or pass `timeout=` on that call |
53
+
54
+ ## UnexpectedAlertPresentException
55
+
56
+ `unexpected alert open: {Alert text : …}`
57
+
58
+ A JavaScript alert, confirm or prompt is open; the step before it triggered the alert. Handle it with `Handle Alert ACCEPT` (or `DISMISS`) right after the step that opens it.
59
+
60
+ ## Unsupported browser name
61
+
62
+ `ValueError: headless_chrome is not a supported browser.`
63
+
64
+ `Open Browser` accepts `headlesschrome` and `headlessfirefox` (no underscore) and no headless Edge name. Use `edge` with `options=add_argument("--headless=new")` for headless Edge.
65
+
66
+ ## SessionNotCreatedException
67
+
68
+ `session not created: This version of ChromeDriver only supports Chrome version NN`
69
+
70
+ Selenium Manager normally fetches the matching driver. A mismatch means a stale driver in `PATH` or in the cache, or an old Selenium:
71
+
72
+ ```bash
73
+ uv lock --upgrade-package selenium && uv sync # newer Selenium Manager
74
+ rm -rf ~/.cache/selenium # drop cached drivers; fetched again on the next Open Browser
75
+ ```
76
+
77
+ Remove any old `chromedriver` from `PATH` so Selenium Manager's driver is used. Selenium Manager cannot download drivers without network access: see rf-setup (plugin rf-core) for offline setup.
78
+
79
+ ## Chrome fails to start in CI or a container
80
+
81
+ `unknown error: DevToolsActivePort file doesn't exist` or `Chrome failed to start: exited abnormally`
82
+
83
+ - No display: run headless (`headlesschrome`, or `options=add_argument("--headless=new")`).
84
+ - Running as root in a container: add `--no-sandbox`.
85
+ - Small `/dev/shm` in Docker: add `--disable-dev-shm-usage`.
86
+
87
+ ```robotframework
88
+ *** Keywords ***
89
+ Open Chrome In Container
90
+ [Arguments] ${url}
91
+ Open Browser ${url} chrome
92
+ ... options=add_argument("--headless=new");add_argument("--no-sandbox");add_argument("--disable-dev-shm-usage");add_argument("--window-size=1920,1080")
93
+ ```
94
+
95
+ ## Clicks have no effect after a login
96
+
97
+ After logging in with a password that Chrome knows from breach lists (demo sites, `password123`), Chrome's password manager shows a leak warning that swallows later clicks, even headless: elements are found, but nothing happens. Turn the password manager off for test browsers:
98
+
99
+ ```robotframework
100
+ *** Variables ***
101
+ ${CHROME_OPTIONS} add_experimental_option("prefs", {"credentials_enable_service": False, "profile.password_manager_enabled": False, "profile.password_manager_leak_detection": False})
102
+
103
+ *** Keywords ***
104
+ Open Test Browser
105
+ Open Browser ${URL} headlesschrome options=${CHROME_OPTIONS}
106
+ ```
107
+
108
+ ## Screenshots, page source and logs
109
+
110
+ - `run_on_failure` (import argument, default `Capture Page Screenshot`) runs whenever a SeleniumLibrary keyword fails, so failures already have a screenshot in the log. `run_on_failure=NOTHING` turns it off; `Register Keyword To Run On Failure Log Source` changes it during a run and returns the previous keyword.
111
+ - `Capture Page Screenshot EMBED` embeds the image in log.html instead of writing a file (useful when only log.html is archived); `filename=` with `{index}` avoids overwriting.
112
+ - `Capture Element Screenshot css:#chart` captures one element.
113
+ - `Log Source` writes the current page (or selected frame) HTML to the log, which shows what the locator was matched against.
114
+ - `Log Location` and `Log Title` record where the browser was.
115
+ - `Set Screenshot Directory` (or the `screenshot_root_directory` import argument) moves screenshot files.
116
+
117
+ Screenshots taken in teardowns duplicate `run_on_failure`; add one only for failures outside SeleniumLibrary keywords (for example a failed `Should Be Equal` on data read earlier):
118
+
119
+ ```robotframework
120
+ *** Settings ***
121
+ Test Teardown Run Keyword If Test Failed Capture Page Screenshot EMBED
122
+ ```
@@ -0,0 +1,84 @@
1
+ # Waits and Timeouts
2
+
3
+ - Which wait keyword
4
+ - Waiting for a count or a custom condition
5
+ - Timeout scopes
6
+ - Implicit wait
7
+ - Patterns
8
+
9
+ ## Which wait keyword
10
+
11
+ Element keywords (`Click Element`, `Input Text`, `Get Text`) and `… Should …` assertions do not wait. Put an explicit wait in front of anything that appears, changes or disappears after page load:
12
+
13
+ | Waiting for | Keyword |
14
+ |---|---|
15
+ | Element shown | `Wait Until Element Is Visible` |
16
+ | Element in the DOM (may be hidden) | `Wait Until Page Contains Element` (`limit=` waits for an exact count) |
17
+ | Element hidden / removed | `Wait Until Element Is Not Visible` / `Wait Until Page Does Not Contain Element` |
18
+ | Element clickable | `Wait Until Element Is Enabled` |
19
+ | Text anywhere / gone | `Wait Until Page Contains` / `Wait Until Page Does Not Contain` |
20
+ | Text in one element | `Wait Until Element Contains` / `Wait Until Element Does Not Contain` |
21
+ | URL change | `Wait Until Location Contains` / `Wait Until Location Is` / `Wait Until Location Does Not Contain` |
22
+ | JavaScript condition | `Wait For Condition return document.readyState == "complete"` |
23
+
24
+ All take `timeout=` and `error=` (custom failure message).
25
+
26
+ ## Waiting for a count or a custom condition
27
+
28
+ SeleniumLibrary has no "wait until element count is …" keyword. Use `limit=` for an exact count, or retry an assertion:
29
+
30
+ ```robotframework
31
+ *** Test Cases ***
32
+ Wait For Three Rows
33
+ Wait Until Page Contains Element css:table#results tr limit=3
34
+
35
+ Wait For At Least Four Items
36
+ Wait Until Keyword Succeeds 10s 500ms Item Count Should Be At Least css:li.item 4
37
+
38
+ *** Keywords ***
39
+ Item Count Should Be At Least
40
+ [Arguments] ${locator} ${minimum}
41
+ ${count}= Get Element Count ${locator}
42
+ Should Be True ${count} >= ${minimum}
43
+ ```
44
+
45
+ `Wait Until Keyword Succeeds` retries a whole keyword; keep the retried keyword free of side effects (no clicks), or a retry repeats them.
46
+
47
+ ## Timeout scopes
48
+
49
+ | Scope | How | Applies to |
50
+ |---|---|---|
51
+ | Library default | `Library SeleniumLibrary timeout=10s` (default 5 s) | `Wait …` keywords, alert keywords, `Execute Async Javascript` |
52
+ | Rest of the suite | `${old}= Set Selenium Timeout 30s` (returns the previous value) | same |
53
+ | One call | `timeout=30s` argument | that call |
54
+ | Page load | `page_load_timeout=` import argument (default 5 min) or `Set Selenium Page Load Timeout` | page loads started by `Open Browser` and `Go To` |
55
+
56
+ Restore a changed timeout in a teardown (`Set Selenium Timeout ${old}`) so later tests keep the default.
57
+
58
+ ## Implicit wait
59
+
60
+ `implicit_wait` (import argument or `Set Selenium Implicit Wait`) makes Selenium retry every element lookup for that long. It defaults to 0 and should stay there:
61
+
62
+ - Every lookup inside a `Wait Until …` poll also blocks, so a wait can run past its `timeout`.
63
+ - Absence checks (`Wait Until Page Does Not Contain Element`, `Page Should Not Contain Element`) pay the full implicit wait on every poll.
64
+ - A missing element fails only after the implicit wait, which makes every genuine failure slow.
65
+
66
+ `Set Selenium Speed` adds a delay after every Selenium command; it is for demos and debugging, not for synchronisation.
67
+
68
+ ## Patterns
69
+
70
+ ```robotframework
71
+ *** Keywords ***
72
+ Submit And Wait For Result
73
+ Wait Until Element Is Enabled id:submit
74
+ Click Element id:submit
75
+ Wait Until Element Is Not Visible css:.spinner timeout=30s
76
+ Wait Until Element Contains id:status Saved
77
+
78
+ Go To And Wait
79
+ [Arguments] ${url} ${ready_locator}
80
+ Go To ${url}
81
+ Wait Until Element Is Visible ${ready_locator}
82
+ ```
83
+
84
+ Wait for the thing the test needs next (a result element, a text), not for a fixed time: `Sleep` either wastes time or is too short on a slow CI machine.
@@ -0,0 +1,120 @@
1
+ """Locate and read the bundled plugin tree at runtime.
2
+
3
+ The bundle lives at ``robotframework_plugins/_assets/`` inside the installed
4
+ wheel. We use ``importlib.resources.files`` (3.9+, stable in 3.12) so
5
+ the same code path works under:
6
+
7
+ * normal pip / pipx wheel installs
8
+ * PEP 660 editable installs
9
+ * zipapp / PyInstaller frozen builds
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ from contextlib import contextmanager
16
+ from importlib.resources import as_file, files
17
+ from pathlib import Path
18
+ from typing import Any, Iterator
19
+
20
+ # Resource root inside the installed package. The build hook copies each
21
+ # bundled plugin to ``_assets/plugins/<name>/`` and writes
22
+ # ``_assets/catalog.json`` at wheel time.
23
+ _ASSETS_RESOURCE_NAME = "_assets"
24
+ #: The plugin an adapter plans when no other is named (tests, old callers):
25
+ #: ``rf-core`` ships the hooks and the subagents every install needs.
26
+ DEFAULT_PLUGIN = "rf-core"
27
+
28
+
29
+ def bundle_root_traversable():
30
+ """Return the whole bundle (catalogue plus plugins) as an importlib Traversable."""
31
+ return files("robotframework_plugins").joinpath(_ASSETS_RESOURCE_NAME)
32
+
33
+
34
+ def asset_root_traversable(plugin: str = DEFAULT_PLUGIN):
35
+ """Return one bundled plugin tree as an importlib Traversable."""
36
+ return bundle_root_traversable().joinpath("plugins", plugin)
37
+
38
+
39
+ @contextmanager
40
+ def asset_root_path(plugin: str = DEFAULT_PLUGIN) -> Iterator[Path]:
41
+ """Yield one bundled plugin tree as a real ``Path``.
42
+
43
+ ``importlib.resources.as_file`` extracts the resource into a
44
+ temporary directory if it lives inside a zip / wheel; for normal
45
+ on-disk installs (the common case) it returns the path directly.
46
+ """
47
+ with as_file(asset_root_traversable(plugin)) as p:
48
+ yield Path(p)
49
+
50
+
51
+ def asset_files(*subpath_parts: str, plugin: str = DEFAULT_PLUGIN) -> Iterator[Path]:
52
+ """Yield every file under ``_assets/plugins/<plugin>/<subpath>`` as a Path.
53
+
54
+ Recurses into subdirectories. Useful for adapters that want to
55
+ walk a category like ``skills/`` or ``agents/``.
56
+ """
57
+ with asset_root_path(plugin) as root:
58
+ target = root.joinpath(*subpath_parts)
59
+ if not target.exists():
60
+ return
61
+ if target.is_file():
62
+ yield target
63
+ return
64
+ for child in sorted(target.rglob("*")):
65
+ if child.is_file():
66
+ yield child
67
+
68
+
69
+ def bundled_catalog() -> list[dict[str, Any]]:
70
+ """The bundled plugins: name, version, tier, status, summary, libraries, ...
71
+
72
+ Empty when the bundle has no catalogue (a broken build).
73
+ """
74
+ try:
75
+ text = bundle_root_traversable().joinpath("catalog.json").read_text(encoding="utf-8")
76
+ except (FileNotFoundError, OSError):
77
+ return []
78
+ return list(json.loads(text).get("plugins", []))
79
+
80
+
81
+ def is_bundle(entry: dict[str, Any]) -> bool:
82
+ """A catalogue entry with no content of its own (``rf-agentskills`` since 4.0.0)."""
83
+ return bool(entry.get("bundle"))
84
+
85
+
86
+ def expand_bundles(names: list[str], catalog: list[dict[str, Any]]) -> list[str]:
87
+ """``names`` with every bundle replaced by the plugins it bundles.
88
+
89
+ File mode copies content per plugin: installing the bundle means
90
+ installing the plugins it ships a copy of. Order is kept; duplicates are dropped."""
91
+ by_name = {p["name"]: p for p in catalog}
92
+ out: list[str] = []
93
+
94
+ def add(name: str, seen: frozenset[str]) -> None:
95
+ entry = by_name.get(name, {})
96
+ if is_bundle(entry) and name not in seen:
97
+ for dep in entry.get("bundled", []):
98
+ add(dep, seen | {name})
99
+ elif name not in out:
100
+ out.append(name)
101
+
102
+ for name in names:
103
+ add(name, frozenset())
104
+ return out
105
+
106
+
107
+ def content_plugins() -> tuple[str, ...]:
108
+ """Every active plugin with content in the bundled catalogue (what a plan
109
+ covers when the caller names none); ``(DEFAULT_PLUGIN,)`` without a catalogue."""
110
+ names = [p["name"] for p in bundled_catalog() if p.get("status") == "active" and not is_bundle(p)]
111
+ if DEFAULT_PLUGIN in names: # rf-core first: the others depend on it
112
+ names.remove(DEFAULT_PLUGIN)
113
+ names.insert(0, DEFAULT_PLUGIN)
114
+ return tuple(names) or (DEFAULT_PLUGIN,)
115
+
116
+
117
+ def relative_to_assets(path: Path, plugin: str = DEFAULT_PLUGIN) -> Path:
118
+ """Compute ``path`` relative to the plugin's asset root, raising if outside."""
119
+ with asset_root_path(plugin) as root:
120
+ return path.resolve().relative_to(root.resolve())
@@ -0,0 +1,123 @@
1
+ """Build catalogue entries from plugin folders.
2
+
3
+ Shared by the wheel's build hook (``hatch_build.py`` loads this file by path,
4
+ because the package isn't importable at build time) and by ``bundle.fetch()``,
5
+ which builds the catalogue of a downloaded repository snapshot. Both must
6
+ produce the same entries, so the rules live here once.
7
+
8
+ Only the standard library and PyYAML (a package dependency) are used.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ import yaml
18
+
19
+ #: Version of the catalogue's shape (``catalog.json`` ``format``). Bumped only
20
+ #: on a breaking change to the documented entry fields; see the README's
21
+ #: "Python API" section.
22
+ CATALOG_FORMAT = 1
23
+ #: Statuses that are bundled; ``removed`` plugins stay out.
24
+ BUNDLED_STATUSES = ("active", "deprecated")
25
+ #: A plugin's own top-level folders that are for this repository's CI, not for
26
+ #: users. Skills ship example ``tests/`` folders too, so only the plugin root.
27
+ PLUGIN_ONLY_DIRS = frozenset({"tests", "evals"})
28
+ _REQUIRED_MANIFEST = ("tier", "status", "summary")
29
+
30
+
31
+ class CatalogError(ValueError):
32
+ """A plugin folder whose manifest can't be turned into a catalogue entry."""
33
+
34
+
35
+ def has_content(plugin_dir: Path) -> bool:
36
+ """Ships a skill, a subagent or a hook."""
37
+ return (any((s / "SKILL.md").is_file() for s in (plugin_dir / "skills").glob("*"))
38
+ or any((plugin_dir / "agents").glob("*.md"))
39
+ or (plugin_dir / "hooks" / "hooks.json").is_file())
40
+
41
+
42
+ def _manifest(plugin_dir: Path) -> dict[str, Any]:
43
+ path = plugin_dir / "catalog.yaml"
44
+ if not path.is_file():
45
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml missing; run scripts/build-catalog.py --check")
46
+ try:
47
+ m = yaml.safe_load(path.read_text(encoding="utf-8"))
48
+ except yaml.YAMLError as exc:
49
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml is not valid YAML ({exc})") from exc
50
+ if not isinstance(m, dict):
51
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml is not a mapping")
52
+ missing = [k for k in _REQUIRED_MANIFEST if not m.get(k)]
53
+ if missing:
54
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml lacks {', '.join(missing)}")
55
+ return m
56
+
57
+
58
+ def _plugin_json(plugin_dir: Path) -> dict[str, Any]:
59
+ path = plugin_dir / ".claude-plugin" / "plugin.json"
60
+ if not path.is_file():
61
+ raise CatalogError(f"{plugin_dir.name}: .claude-plugin/plugin.json missing")
62
+ try:
63
+ pj = json.loads(path.read_text(encoding="utf-8"))
64
+ except json.JSONDecodeError as exc:
65
+ raise CatalogError(f"{plugin_dir.name}: plugin.json is not valid JSON ({exc})") from exc
66
+ if not isinstance(pj, dict) or not pj.get("version"):
67
+ raise CatalogError(f"{plugin_dir.name}: plugin.json lacks version")
68
+ return pj
69
+
70
+
71
+ def catalog_entries(plugins_dir: Path) -> list[dict[str, Any]]:
72
+ """One entry per bundled plugin under ``plugins_dir``, from its catalog.yaml and plugin.json."""
73
+ entries = []
74
+ for d in sorted(p for p in plugins_dir.iterdir() if p.is_dir()):
75
+ m = _manifest(d)
76
+ if m["status"] not in BUNDLED_STATUSES:
77
+ continue
78
+ pj = _plugin_json(d)
79
+ deps = [x if isinstance(x, str) else x["name"] for x in pj.get("dependencies", [])]
80
+ entry = {
81
+ "name": d.name,
82
+ "version": pj.get("version"),
83
+ "tier": m["tier"],
84
+ "status": m["status"],
85
+ "summary": m["summary"],
86
+ "libraries": m.get("libraries", []),
87
+ "robotframework": str(m.get("robotframework", "")),
88
+ "dependencies": deps,
89
+ # A bundle ships a copy of other plugins (catalog.yaml ``bundle``) and
90
+ # no content of its own; file mode installs those plugins instead.
91
+ "bundle": bool(m.get("bundle")) and not has_content(d),
92
+ "bundled": list(m.get("bundle", [])),
93
+ }
94
+ for key in ("replacement", "deprecated_since"):
95
+ if key in m:
96
+ entry[key] = str(m[key])
97
+ entries.append(entry)
98
+ return entries
99
+
100
+
101
+ def catalog_document(entries: list[dict[str, Any]]) -> str:
102
+ """The ``catalog.json`` text for ``entries``."""
103
+ return json.dumps({"format": CATALOG_FORMAT, "plugins": entries}, indent=2, ensure_ascii=False) + "\n"
104
+
105
+
106
+ #: The plugin listed first by ``skills_dirs()``: the others depend on it.
107
+ CORE_PLUGIN = "rf-core"
108
+
109
+
110
+ def skill_dirs(entries: list[dict[str, Any]], root: Path) -> dict[str, Path]:
111
+ """``{name: <root>/plugins/<name>/skills}`` for every active plugin in ``entries``
112
+ that isn't a bundle and has at least one ``*/SKILL.md``; ``rf-core`` first,
113
+ then catalogue order."""
114
+ names = [e["name"] for e in entries if e.get("status") == "active" and not e.get("bundle")]
115
+ if CORE_PLUGIN in names:
116
+ names.remove(CORE_PLUGIN)
117
+ names.insert(0, CORE_PLUGIN)
118
+ out: dict[str, Path] = {}
119
+ for name in names:
120
+ skills = root / "plugins" / name / "skills"
121
+ if any(skills.glob("*/SKILL.md")):
122
+ out[name] = skills.resolve()
123
+ return out
@@ -0,0 +1,230 @@
1
+ """Snapshots of the plugins at a ref of the repository (``bundle.fetch()``).
2
+
3
+ The only code in the package that uses the network, and only when
4
+ ``fetch()`` is called. The installer's commands never import it.
5
+
6
+ 1. Resolve the ref to a commit SHA (a full SHA is taken as is).
7
+ 2. Reuse ``<cache>/<sha>/`` when a finished snapshot is there.
8
+ 3. Download the commit's archive from GitHub, with a timeout and size caps.
9
+ 4. Check every archive entry, and extract ``plugins/`` by hand: only regular
10
+ files and directories, no absolute paths, no ``..``.
11
+ 5. Build the catalogue with the wheel's rules (``_catalog``), then move the
12
+ finished folder into the cache in one step.
13
+
14
+ Nothing from the snapshot is imported or run.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import copy
20
+ import datetime as _dt
21
+ import http.client
22
+ import json
23
+ import os
24
+ import re
25
+ import shutil
26
+ import tarfile
27
+ import tempfile
28
+ import urllib.error
29
+ import urllib.parse
30
+ import urllib.request
31
+ from dataclasses import dataclass
32
+ from pathlib import Path, PurePosixPath
33
+ from typing import Any
34
+
35
+ from . import __version__, _catalog
36
+
37
+ REPOSITORY = "MarketSquare/robotframework-plugins"
38
+ #: Base URLs; tests point them at a local server.
39
+ GITHUB_API = "https://api.github.com"
40
+ CODELOAD = "https://codeload.github.com"
41
+ #: Caps on the compressed download and on what it may expand to.
42
+ MAX_ARCHIVE_BYTES = 64 * 1024 * 1024
43
+ MAX_EXTRACTED_BYTES = 512 * 1024 * 1024
44
+ _SHA = re.compile(r"[0-9a-f]{40}")
45
+ _DONE = "snapshot.json"
46
+
47
+
48
+ class FetchError(RuntimeError):
49
+ """A snapshot couldn't be fetched or failed its checks; the cache is unchanged."""
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class Snapshot:
54
+ """The plugins at one commit of the repository, extracted in the cache."""
55
+
56
+ ref: str
57
+ commit: str
58
+ path: Path
59
+
60
+ def catalog(self) -> list[dict[str, Any]]:
61
+ """The snapshot's plugins (active and deprecated), as ``bundle.catalog()``."""
62
+ doc = json.loads((self.path / "catalog.json").read_text(encoding="utf-8"))
63
+ return copy.deepcopy(list(doc.get("plugins", [])))
64
+
65
+ def skills_dirs(self) -> dict[str, Path]:
66
+ """``{plugin: skills folder}`` of the snapshot, as ``bundle.skills_dirs()``."""
67
+ return _catalog.skill_dirs(self.catalog(), self.path)
68
+
69
+
70
+ def default_cache_dir() -> Path:
71
+ if os.name == "nt":
72
+ base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
73
+ else:
74
+ base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
75
+ return base / "robotframework-plugins" / "snapshots"
76
+
77
+
78
+ def fetch(ref: str = "stable", *, cache_dir: str | os.PathLike[str] | None = None,
79
+ timeout: float = 30.0) -> Snapshot:
80
+ ref = str(ref).strip()
81
+ if not ref:
82
+ raise FetchError("ref is empty")
83
+ cache = Path(cache_dir) if cache_dir is not None else default_cache_dir()
84
+ sha = ref.lower() if _SHA.fullmatch(ref.lower()) else None
85
+ if sha is None:
86
+ sha = _resolve(ref, timeout)
87
+ hit = _cached(cache, sha, ref)
88
+ if hit is not None:
89
+ return hit
90
+ return _build(ref, sha, cache, timeout)
91
+
92
+
93
+ def _cached(cache: Path, sha: str, ref: str) -> Snapshot | None:
94
+ folder = cache / sha
95
+ if (folder / _DONE).is_file() and (folder / "catalog.json").is_file():
96
+ return Snapshot(ref=ref, commit=sha, path=folder.resolve())
97
+ return None
98
+
99
+
100
+ def _request(url: str, accept: str) -> urllib.request.Request:
101
+ return urllib.request.Request(url, headers={"Accept": accept, "User-Agent": f"robotframework-plugins/{__version__}"})
102
+
103
+
104
+ def _resolve(ref: str, timeout: float) -> str:
105
+ url = f"{GITHUB_API}/repos/{REPOSITORY}/commits/{urllib.parse.quote(ref, safe='/')}"
106
+ try:
107
+ with urllib.request.urlopen(_request(url, "application/vnd.github.sha"), timeout=timeout) as resp:
108
+ body = resp.read(200).decode("ascii", "replace").strip()
109
+ except urllib.error.HTTPError as exc:
110
+ if exc.code in (404, 422):
111
+ raise FetchError(f"ref {ref!r} not found in {REPOSITORY}") from exc
112
+ raise FetchError(f"resolving ref {ref!r} failed: HTTP {exc.code}") from exc
113
+ except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
114
+ raise FetchError(f"resolving ref {ref!r} failed: {_reason(exc)}") from exc
115
+ if not _SHA.fullmatch(body):
116
+ raise FetchError(f"resolving ref {ref!r} returned no commit SHA")
117
+ return body
118
+
119
+
120
+ def _reason(exc: BaseException) -> str:
121
+ reason = getattr(exc, "reason", None) or exc
122
+ return f"{type(reason).__name__}: {reason}"
123
+
124
+
125
+ def _build(ref: str, sha: str, cache: Path, timeout: float) -> Snapshot:
126
+ try:
127
+ cache.mkdir(parents=True, exist_ok=True)
128
+ work = Path(tempfile.mkdtemp(prefix=f".tmp-{sha[:12]}-", dir=cache))
129
+ except OSError as exc:
130
+ raise FetchError(f"cache folder {cache} is not writable: {exc}") from exc
131
+ try:
132
+ archive = work / "archive.tar.gz"
133
+ _download(sha, archive, timeout)
134
+ snap = work / "snapshot"
135
+ _extract_plugins(archive, snap)
136
+ try:
137
+ entries = _catalog.catalog_entries(snap / "plugins")
138
+ except _catalog.CatalogError as exc:
139
+ raise FetchError(f"snapshot {sha[:12]}: {exc}") from exc
140
+ (snap / "catalog.json").write_text(_catalog.catalog_document(entries), encoding="utf-8")
141
+ (snap / _DONE).write_text(json.dumps({
142
+ "repository": REPOSITORY, "ref": ref, "commit": sha,
143
+ "fetched_at": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"), # noqa: UP017 (3.10)
144
+ }, indent=2) + "\n", encoding="utf-8")
145
+ target = cache / sha
146
+ try:
147
+ os.replace(snap, target)
148
+ except OSError:
149
+ # Another process finished the same snapshot first: use its folder.
150
+ hit = _cached(cache, sha, ref)
151
+ if hit is None:
152
+ raise
153
+ return hit
154
+ return Snapshot(ref=ref, commit=sha, path=target.resolve())
155
+ finally:
156
+ shutil.rmtree(work, ignore_errors=True)
157
+
158
+
159
+ def _download(sha: str, dest: Path, timeout: float) -> None:
160
+ url = f"{CODELOAD}/{REPOSITORY}/tar.gz/{sha}"
161
+ size = 0
162
+ try:
163
+ with urllib.request.urlopen(_request(url, "application/octet-stream"), timeout=timeout) as resp, \
164
+ dest.open("wb") as out:
165
+ while chunk := resp.read(1024 * 1024):
166
+ size += len(chunk)
167
+ if size > MAX_ARCHIVE_BYTES:
168
+ raise FetchError(f"archive of {sha[:12]} is larger than {MAX_ARCHIVE_BYTES // 2**20} MB")
169
+ out.write(chunk)
170
+ except urllib.error.HTTPError as exc:
171
+ raise FetchError(f"downloading {sha[:12]} failed: HTTP {exc.code}") from exc
172
+ except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
173
+ raise FetchError(f"downloading {sha[:12]} failed: {_reason(exc)}") from exc
174
+
175
+
176
+ def _safe_parts(name: str) -> tuple[str, ...]:
177
+ path = PurePosixPath(name.replace("\\", "/"))
178
+ parts = tuple(p for p in path.parts if p not in ("", "."))
179
+ if path.is_absolute() or ".." in parts or (parts and ":" in parts[0]):
180
+ raise FetchError(f"archive entry {name!r} leaves the snapshot folder")
181
+ return parts
182
+
183
+
184
+ def _extract_plugins(archive: Path, dest: Path) -> None:
185
+ """Check every entry, then write ``<top>/plugins/**`` (minus plugin tests/evals) to ``dest/plugins``."""
186
+ try:
187
+ with tarfile.open(archive, "r:gz") as tf:
188
+ members = tf.getmembers()
189
+ _check_members(members)
190
+ written = _write_plugins(tf, members, dest)
191
+ except (tarfile.TarError, EOFError) as exc:
192
+ raise FetchError(f"archive is not a readable gzip tarball: {exc}") from exc
193
+ except OSError as exc:
194
+ raise FetchError(f"extracting the archive failed: {exc}") from exc
195
+ if not written or not (dest / "plugins").is_dir():
196
+ raise FetchError("archive has no plugins/ folder")
197
+
198
+
199
+ def _check_members(members: list[tarfile.TarInfo]) -> None:
200
+ total = 0
201
+ for m in members:
202
+ _safe_parts(m.name)
203
+ if not (m.isfile() or m.isdir()):
204
+ raise FetchError(f"archive entry {m.name!r} is a link or a special file")
205
+ total += m.size if m.isfile() else 0
206
+ if total > MAX_EXTRACTED_BYTES:
207
+ raise FetchError(f"archive expands to more than {MAX_EXTRACTED_BYTES // 2**20} MB")
208
+
209
+
210
+ def _write_plugins(tf: tarfile.TarFile, members: list[tarfile.TarInfo], dest: Path) -> int:
211
+ written = 0
212
+ for m in members:
213
+ parts = _safe_parts(m.name)
214
+ # <top>/plugins/<plugin>/...; a plugin's own tests/ and evals/ stay out.
215
+ if len(parts) < 3 or parts[1] != "plugins":
216
+ continue
217
+ if len(parts) > 3 and parts[3] in _catalog.PLUGIN_ONLY_DIRS:
218
+ continue
219
+ target = dest.joinpath("plugins", *parts[2:])
220
+ if m.isdir():
221
+ target.mkdir(parents=True, exist_ok=True)
222
+ continue
223
+ src = tf.extractfile(m)
224
+ if src is None:
225
+ raise FetchError(f"archive entry {m.name!r} can't be read")
226
+ target.parent.mkdir(parents=True, exist_ok=True)
227
+ with src, target.open("wb") as out:
228
+ shutil.copyfileobj(src, out)
229
+ written += 1
230
+ return written