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.
- robotframework_plugins/__init__.py +14 -0
- robotframework_plugins/_assets/catalog.json +143 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
- robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +110 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
- robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
- robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
- robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
- robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
- robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
- robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
- robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
- robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
- robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
- robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
- robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
- robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
- robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
- robotframework_plugins/_assets.py +120 -0
- robotframework_plugins/_catalog.py +123 -0
- robotframework_plugins/_snapshot.py +230 -0
- robotframework_plugins/adapters/__init__.py +53 -0
- robotframework_plugins/adapters/_base.py +400 -0
- robotframework_plugins/adapters/claude_code.py +312 -0
- robotframework_plugins/adapters/claude_desktop.py +129 -0
- robotframework_plugins/adapters/codex.py +276 -0
- robotframework_plugins/adapters/copilot.py +87 -0
- robotframework_plugins/adapters/cursor.py +295 -0
- robotframework_plugins/adapters/goose.py +240 -0
- robotframework_plugins/adapters/opencode.py +170 -0
- robotframework_plugins/bundle.py +85 -0
- robotframework_plugins/cli.py +1311 -0
- robotframework_plugins/detect.py +121 -0
- robotframework_plugins/manifest.py +338 -0
- robotframework_plugins/py.typed +0 -0
- robotframework_plugins/skillzip.py +39 -0
- robotframework_plugins/transforms.py +725 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md
ADDED
|
@@ -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
|
+
```
|
robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md
ADDED
|
@@ -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
|