robotframework-plugins 2026.11.0__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 (199) 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 +113 -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/async-jobs.md +42 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/loose-assertions.md +20 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +120 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/loose-assertions.md +18 -0
  31. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  32. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  33. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  34. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  35. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +13 -0
  36. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  37. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +120 -0
  38. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  39. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  40. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  41. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +445 -0
  42. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +128 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  50. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  51. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +517 -0
  52. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  108. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  109. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  110. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +119 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +123 -0
  115. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  116. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  117. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +10 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +268 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  128. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  129. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  130. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  143. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  144. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  145. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  146. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  147. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  148. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  149. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +134 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/selector-drift.md +29 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  172. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  173. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  174. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  175. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  176. robotframework_plugins/_assets.py +120 -0
  177. robotframework_plugins/_catalog.py +123 -0
  178. robotframework_plugins/_snapshot.py +320 -0
  179. robotframework_plugins/adapters/__init__.py +53 -0
  180. robotframework_plugins/adapters/_base.py +400 -0
  181. robotframework_plugins/adapters/claude_code.py +312 -0
  182. robotframework_plugins/adapters/claude_desktop.py +129 -0
  183. robotframework_plugins/adapters/codex.py +276 -0
  184. robotframework_plugins/adapters/copilot.py +87 -0
  185. robotframework_plugins/adapters/cursor.py +295 -0
  186. robotframework_plugins/adapters/goose.py +240 -0
  187. robotframework_plugins/adapters/opencode.py +170 -0
  188. robotframework_plugins/bundle.py +85 -0
  189. robotframework_plugins/cli.py +1311 -0
  190. robotframework_plugins/detect.py +121 -0
  191. robotframework_plugins/manifest.py +338 -0
  192. robotframework_plugins/py.typed +0 -0
  193. robotframework_plugins/skillzip.py +39 -0
  194. robotframework_plugins/transforms.py +725 -0
  195. robotframework_plugins-2026.11.0.dist-info/METADATA +198 -0
  196. robotframework_plugins-2026.11.0.dist-info/RECORD +199 -0
  197. robotframework_plugins-2026.11.0.dist-info/WHEEL +4 -0
  198. robotframework_plugins-2026.11.0.dist-info/entry_points.txt +2 -0
  199. robotframework_plugins-2026.11.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,268 @@
1
+ ---
2
+ name: rf-platynui
3
+ description: "Use first, before answering, for RF desktop app tests with PlatynUI: windows, dialogs."
4
+ license: Apache-2.0
5
+ compatibility: Requires Python 3.12+, robotframework>=7, robotcode[all]>=2.8 in the project environment and the PlatynUI new_core pre-release (robotframework-PlatynUI 0.12.0.dev); Windows (UIA) or a Linux desktop with AT-SPI2. macOS is not supported.
6
+ metadata:
7
+ author: manykarim
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # PlatynUI Library Skill (new_core / BareMetal)
12
+
13
+ ## When to use
14
+
15
+ Load this skill first, before exploring the project or answering from memory, when a Robot Framework test drives a native desktop application with PlatynUI (Windows UIA, Linux AT-SPI2):
16
+
17
+ - windows, dialogs, menus and controls found with XPath over the desktop tree; clicking, typing, keyboard shortcuts, reading control text;
18
+ - platynui-cli or the inspector to build locators;
19
+ - a desktop test cannot find a button, menu or dialog, or the user automates Calculator, Notepad or a Qt/GTK/WPF/WinForms app, even if they only say "desktop app".
20
+
21
+ Not this skill: mobile apps use `rf-appium` (plugin `rf-mobile`); web browsers use `rf-browser` (plugin `rf-web`) or `rf-selenium`; installing PlatynUI pre-releases uses `rf-setup` (plugin `rf-core`).
22
+
23
+ ## Quick Reference
24
+
25
+ PlatynUI is cross-platform **native desktop** UI automation for Robot Framework. It normalizes Windows UIA, Linux AT-SPI2 (and planned macOS AX) into one desktop UI model that you query with **XPath-2.0-style selectors**.
26
+
27
+ > ⚠️ **Preview / pre-release.** This skill targets the `new_core` rewrite. The only usable keyword library today is **`PlatynUI.BareMetal`**; the high-level `PlatynUI` library is a not-yet-implemented placeholder. Keywords, CLI output, and behavior may change.
28
+
29
+ ## Installation
30
+
31
+ Install into the project environment, with the tool the project already uses. Full steps and verification: `references/install.md`. For a new environment, Poetry and venv + pip forms, and troubleshooting, see `rf-setup` (plugin `rf-core`).
32
+
33
+ **Get the version with the right pin — this is the #1 mistake:**
34
+
35
+ ```bash
36
+ # ✅ new_core (PlatynUI.BareMetal, documented keywords) — pin OR opt into pre-releases:
37
+ uv add robotframework-PlatynUI==0.12.0.dev330 # verified pin # pip: pip install robotframework-PlatynUI==0.12.0.dev330
38
+ uv add --prerelease allow robotframework-PlatynUI # latest pre-release # pip: pip install --pre robotframework-PlatynUI
39
+
40
+ # ❌ WRONG — installs old 0.9.2 (a different library, NO BareMetal):
41
+ uv add robotframework-PlatynUI # no pin, no --prerelease allow → 0.9.2
42
+ ```
43
+
44
+ - An unpinned install without the pre-release opt-in (`uv add robotframework-PlatynUI`, or plain pip without `--pre`) resolves the **old stable `0.9.2`**, whose surface is a different, near-undocumented `PlatynUI` library with **no `BareMetal`**. You only get `new_core` by opting into the pre-release (`--prerelease allow` / pip `--pre`) or pinning an exact dev version.
45
+ - The wheel is **prebuilt** — it bundles the compiled `platynui-native` runtime (`_native.abi3.so`). **No Rust toolchain and no git checkout required.** Python **3.12+** only.
46
+ - Optional CLI / inspector tools (for locator development — see below):
47
+ ```bash
48
+ uv tool install --prerelease allow platynui-cli
49
+ uv tool install --prerelease allow platynui-inspector
50
+ ```
51
+ - **Linux** additionally needs a running **AT-SPI2** accessibility bus and (recommended) an **X11** session — see `references/platform-setup.md`.
52
+
53
+ ## Library Import
54
+
55
+ ```robotframework
56
+ *** Settings ***
57
+ Library PlatynUI.BareMetal
58
+ ```
59
+
60
+ Import arguments (all keyword-only, all optional):
61
+
62
+ | Argument | Default | Purpose |
63
+ |----------|---------|---------|
64
+ | `auto_activate` | `True` | Bring the target element's window to the foreground before pointer/keyboard actions. Override per-call with `activate=`. |
65
+ | `use_mock` | `False` | Use the Rust mock provider (deterministic, no desktop). **Note:** the published wheel is built *without* mock support and raises `ProviderError`; needs a `--features mock-provider` source build. |
66
+ | `keyboard_profile` / `pointer_profile` / `pointer_settings` | `None` | Tune input timing/motion realism. Accept a native object **or** a plain `&{dict}` (e.g. `press_delay_ms`, `acceleration_profile`, `motion`). |
67
+
68
+ ```robotframework
69
+ Library PlatynUI.BareMetal auto_activate=${True} pointer_profile=${POINTER_PROFILE}
70
+
71
+ *** Variables ***
72
+ &{POINTER_PROFILE} acceleration_profile=EASE_OUT motion=JITTER jitter_amplitude=100.0
73
+ ```
74
+
75
+ Library scope is **SUITE**. The native runtime is created lazily on first keyword use (so `libdoc` and import work without a desktop).
76
+
77
+ **Check a keyword** before you use it: `robotcode doc keyword PlatynUI.BareMetal "<Keyword>"` prints its arguments, and `robotcode doc keywords PlatynUI.BareMetal "<text>"` searches by name. Use them instead of parsing a libdoc file or reading the library source.
78
+
79
+ ## Essential Concepts
80
+
81
+ ### The normalized desktop UI model
82
+
83
+ PlatynUI exposes every application's accessibility tree as one queryable model rooted at the **Desktop**. Each node has a normalized PascalCase **role** (`Window`, `Button`, `Edit`, `ListItem`…), a `Name`, an optional developer `Id`, and typed attributes (`Bounds`, `IsEnabled`, `Value`…). Native roles are normalized cross-platform (UIA `Button` / AT-SPI `PUSH_BUTTON` → `Button`); the original stays under `native:Role`.
84
+
85
+ ### Four query namespaces
86
+
87
+ ```
88
+ control: UI controls (Window, Button, Edit, …) ← DEFAULT (unprefixed = control:)
89
+ item: container children (ListItem, TreeItem, TabItem, Cell, Row)
90
+ app: Application/process nodes
91
+ native: raw platform attributes (native:HWND, native:Role, …)
92
+ ```
93
+
94
+ **Critical rule:** an unprefixed query matches `control:` **only**. You MUST prefix `app:` and `item:` explicitly — `//ListItem` finds nothing; `//item:ListItem` works.
95
+
96
+ ### XPath query language
97
+
98
+ Elements are referenced by an **XPath string** passed directly as a keyword argument (auto-converted to an element descriptor), or by a `UiNode` captured from `Query ... only_first=${True}`.
99
+
100
+ ```robotframework
101
+ Pointer Click //control:Button[@Name="OK"]
102
+ Pointer Click app:Application[@Name="Calculator"]//Button[@Id="num5Button"]
103
+ ${count}= Query count(//control:Button) # value expression
104
+ ${node}= Query //control:Edit[@Name="Search"] only_first=${True}
105
+ ```
106
+
107
+ Supports the full XPath-2.0 axis/function set: `//` (descendant), `..`/`parent::`, `following-sibling::`, predicates (`[@Name='OK']`, `[1]`), and functions (`contains()`, `matches()`, `count()`, `starts-with()`). See `references/locators-and-queries.md`.
108
+
109
+ ### Lazy resolution with built-in wait
110
+
111
+ There is **no explicit "wait for element" keyword.** When a descriptor is first used, PlatynUI polls the query (default **~30 s**, retrying ~0.1 s) until the element resolves or it raises `ElementNotFoundError`. Write the correct selector and let the runtime wait — don't add `Sleep`.
112
+
113
+ ### Coordinate semantics (pointer keywords)
114
+
115
+ | You pass | Behavior |
116
+ |----------|----------|
117
+ | descriptor, no x/y | acts at the element's `ActivationPoint` (else bounds center) |
118
+ | descriptor **+** x/y | x/y are **offsets** from the element's top-left bounds |
119
+ | no descriptor, x/y | x/y are **absolute screen** coordinates |
120
+ | only one of x/y | `ValueError` — pass both together |
121
+
122
+ ### Window keywords need a window node
123
+
124
+ `Activate/Minimize/Maximize/Restore/Close/Move/Resize Window` operate on a node that supports the window surface — target a `Window` node, not an arbitrary control, or they raise `PatternError`.
125
+
126
+ ## Core Keywords Quick Reference
127
+
128
+ ### Query & scope
129
+
130
+ ```robotframework
131
+ ${node}= Query //control:Button[@Name="OK"] only_first=${True}
132
+ ${all}= Query //item:ListItem # list of nodes
133
+ ${n}= Query count(//control:Button) # computed value
134
+ Set Root app:Application[@Name="Calculator"]//control:Window # scope later queries
135
+ Set Root ${None} # reset to desktop
136
+ ```
137
+
138
+ ### Pointer / mouse
139
+
140
+ ```robotframework
141
+ Pointer Click //control:Button[@Name="OK"]
142
+ Pointer Click //control:Button[@Name="OK"] button=RIGHT activate=${False}
143
+ Pointer Multi Click //item:ListItem[@Name="file.txt"] clicks=${2}
144
+ Pointer Move To ${None} x=${100} y=${200} # absolute screen
145
+ Pointer Press //control:Slider
146
+ Pointer Release ${None}
147
+ ${pos}= Get Pointer Position
148
+ ```
149
+
150
+ ### Keyboard
151
+
152
+ ```robotframework
153
+ Keyboard Type //control:Edit[@Name="Search"] Hello <Ctrl+A> world${\n}
154
+ Keyboard Type ${None} <Ctrl+A><Delete> # type into whatever has focus
155
+ Keyboard Press ${None} <Shift>
156
+ Keyboard Release ${None} <Shift>
157
+ ```
158
+ Key syntax: `<Ctrl+A>`, `<Return>`, `<ESC>`, `<Shift+Tab>`, plain text, `${\n}`. Pass `${None}` as the descriptor to skip focusing. Discover valid key names with `platynui-cli keyboard list`.
159
+
160
+ ### Focus, attributes, windows
161
+
162
+ ```robotframework
163
+ Focus //control:Button[@Name="New File"]
164
+ ${bounds}= Get Attribute //control:Window[@Name="Calc"] Bounds
165
+ Get Attribute //control:Button[@Name="OK"] Name == OK # built-in assertion
166
+ Bring To Front //control:Window[@Name="Calc"]
167
+ Activate Window //control:Window[@Name="Calc"]
168
+ Maximize Window //control:Window[@Name="Calc"]
169
+ Move And Resize Window //control:Window[@Name="Calc"] ${0} ${0} ${800} ${600}
170
+ ```
171
+
172
+ ### Diagnostics
173
+
174
+ ```robotframework
175
+ Take Screenshot # full screen → ${OUTPUT DIR}
176
+ Take Screenshot //control:Window[@Name="Calc"] # just the element
177
+ Take Screenshot filename=EMBED # inline base64 in the log
178
+ Highlight //control:Button[@Name="OK"] duration=${2} # draw an overlay (debug)
179
+ ```
180
+
181
+ ## Locator Strategy
182
+
183
+ 1. **Default namespace is `control`** — `//Button` ≡ `//control:Button`. Add `control:` only for clarity.
184
+ 2. **Always prefix `app:` and `item:`** — applications and container items are NOT in the default namespace. Forgetting this is the most common cause of "element not found."
185
+ 3. **Prefer `@Id` over `@Name`** — `[@Id="num5Button"]` is language-independent and stable (UIA AutomationId / AT-SPI accessible_id / AX AXIdentifier). Use `@Name` only when no Id exists.
186
+ 4. **Anchor on the application, then descend** — `app:Application[@Name='…']//control:Window//control:Button[@Id='…']`. Or `Set Root` once on the app/window and use short relative queries (`.//Button[@Id='…']`).
187
+ 5. **Handle localization with `or`** — `[@Name='Calculator' or @Name='Rechner']`.
188
+ 6. **Fuzzy match with functions** — `contains(@Name,'Save')`, `matches(@Name,'.*Save.*')`, `[contains(@*,'Close')]` (search across all attributes).
189
+ 7. **Step axes when structure beats identity** — `…/Label[@Name='5']/parent::Button`.
190
+ 8. **Let resolution wait** — don't `Sleep`; the descriptor retries for ~30 s.
191
+
192
+ ## Common Patterns
193
+
194
+ ### Launch an app, scope to it, act
195
+
196
+ ```robotframework
197
+ *** Settings ***
198
+ Library PlatynUI.BareMetal
199
+ Library Process
200
+ Test Setup Start Calculator
201
+
202
+ *** Keywords ***
203
+ Start Calculator
204
+ Start Process calc.exe
205
+ # Prefer letting the next Query wait over a fixed Sleep.
206
+
207
+ Enter Digit
208
+ [Arguments] ${d}
209
+ Set Root app:Application[@Name="ApplicationFrameHost"]/control:Window[@Name="Calculator" or @Name="Rechner"]
210
+ Pointer Click .//control:Button[@Id="num${d}Button"]
211
+ ```
212
+
213
+ ### Type into a field and assert
214
+
215
+ ```robotframework
216
+ Keyboard Type //control:Edit[@Name="Search"] robot framework${\n}
217
+ Get Attribute //control:Edit[@Name="Search"] Value == robot framework
218
+ ```
219
+
220
+ ### Verify targeting before automating
221
+
222
+ ```robotframework
223
+ ${node}= Query //control:Button[@Name="Submit"] only_first=${True}
224
+ Highlight ${node} duration=${2} # visually confirm you matched the right node
225
+ Pointer Click ${node}
226
+ ```
227
+
228
+ ## CLI Tooling (locator development loop)
229
+
230
+ Develop and debug selectors with `platynui-cli` before baking them into tests:
231
+
232
+ ```bash
233
+ platynui-cli list-providers # confirm a provider is active
234
+ platynui-cli query "//control:Button[@Name='OK']" # test a selector live
235
+ platynui-cli snapshot "//control:Window" --pretty # dump a UI subtree
236
+ platynui-cli highlight "//control:Button[@Name='OK']" # visually confirm on screen
237
+ ```
238
+
239
+ `platynui-inspector` is a GUI that shows the live UI tree, lets you test XPath interactively, and highlights matches. See `references/cli-and-inspector.md`.
240
+
241
+ ## Troubleshooting
242
+
243
+ - **An unpinned install without pre-release opt-in gives a library with no `BareMetal`** → you got `0.9.2`; reinstall with `uv add --prerelease allow robotframework-PlatynUI` or pin `==0.12.0.dev330`.
244
+ - **Linux: queries return nothing / empty tree** → AT-SPI2 not running, or accessibility not enabled. See `references/platform-setup.md` (`platynui-cli list-providers` should show the `atspi` provider active).
245
+ - **Wayland: clicks land wrong / screenshots fail** → use an X11 (or XWayland) session; Wayland is degraded for input injection and screen coordinates.
246
+ - **`ElementNotFoundError`** → check the namespace prefix (`item:`/`app:`), prefer `@Id`, and verify the selector with `platynui-cli query`.
247
+ - **`ProviderError: requires building with feature 'mock-provider'`** → `use_mock=${True}` needs a source build; the published wheel has no mock provider.
248
+
249
+ ## When to Load Additional References
250
+
251
+ | Need | Reference File |
252
+ |------|----------------|
253
+ | Installing the pre-release, verifying it, or a failed install | `references/install.md` |
254
+ | Full keyword signatures, args, return types | `references/keywords-reference.md` |
255
+ | XPath syntax, namespaces, roles, axes, locator best practices | `references/locators-and-queries.md` |
256
+ | `platynui-cli` subcommands + the inspector | `references/cli-and-inspector.md` |
257
+ | Install matrix, Linux AT-SPI/X11/Wayland, mock, Docker | `references/platform-setup.md` |
258
+ | BareMetal-vs-high-level status, version footgun, migration | `references/status-and-migration.md` |
259
+
260
+ ## Companion Skills
261
+
262
+ | Need | Skill |
263
+ |------|-------|
264
+ | Mobile app tests with AppiumLibrary | `rf-appium` (plugin `rf-mobile`) |
265
+ | Install Robot Framework or a library, fix the environment | `rf-setup` (plugin `rf-core`) |
266
+ | Write tests, suites, user keywords, resources and variables in Robot Framework syntax | `rf-language` (plugin `rf-core`) |
267
+
268
+ For running, discovering, keyword documentation, result analysis and debugging with the robotcode CLI, use the `robotcode` skill of the robotcode plugin (`robotcode@robotframework-agent-plugins`). Look up PlatynUI keywords with `robotcode doc keywords PlatynUI.BareMetal "<text>"` and `robotcode doc keyword PlatynUI.BareMetal "<Keyword>"`, and check changed files with `robotcode analyze code <files>`.
@@ -0,0 +1,45 @@
1
+ *** Settings ***
2
+ # Live desktop example — drives the OS Calculator with PlatynUI.BareMetal.
3
+ #
4
+ # REQUIRES A REAL DESKTOP:
5
+ # - robotframework-PlatynUI new_core: uv add --prerelease allow robotframework-PlatynUI
6
+ # - Windows, or Linux with a running AT-SPI2 bus on an X11 (or XWayland) session
7
+ # (see references/platform-setup.md). Wayland is degraded for pointer/coords.
8
+ #
9
+ # Pattern shown: launch via Process, Set Root on the app window, locate digit
10
+ # buttons by stable @Id with relative queries, then assert the result.
11
+ Library PlatynUI.BareMetal
12
+ Library Process
13
+ Library Collections
14
+
15
+ Suite Setup Launch Calculator
16
+ Suite Teardown Terminate All Processes
17
+
18
+ *** Variables ***
19
+ # ApplicationFrameHost hosts the UWP Calculator on Windows; localized window
20
+ # names handled with `or`. Adjust the anchor for your platform/app.
21
+ ${CALC_WINDOW} app:Application[@Name="ApplicationFrameHost"]/control:Window[@Name="Calculator" or @Name="Rechner"]
22
+
23
+ *** Test Cases ***
24
+ Add Two Numbers
25
+ [Documentation] Click 2, +, 3, = and verify the display shows 5.
26
+ Scope To Calculator
27
+ Press Digit 2
28
+ Pointer Click .//control:Button[@Name="Plus" or @Name="Add"]
29
+ Press Digit 3
30
+ Pointer Click .//control:Button[@Name="Equals" or @Name="Gleich"]
31
+ # The results text exposes its value via the Name/Value attribute:
32
+ Get Attribute .//control:Text[@Id="CalculatorResults"] Name contains 5
33
+
34
+ *** Keywords ***
35
+ Launch Calculator
36
+ Start Process calc.exe
37
+ # No Sleep needed: the first query below retries (~30s) until the window appears.
38
+
39
+ Scope To Calculator
40
+ Set Root ${CALC_WINDOW}
41
+
42
+ Press Digit
43
+ [Arguments] ${digit}
44
+ # @Id is language-independent and stable — prefer it over @Name.
45
+ Pointer Click .//control:Button[@Id="num${digit}Button"]
@@ -0,0 +1,33 @@
1
+ *** Settings ***
2
+ # TEACHING EXAMPLE ONLY — does NOT run against the published pip wheel.
3
+ #
4
+ # `use_mock=${True}` exercises the Rust mock provider (a simulated desktop, no
5
+ # display, fully deterministic). It is the ideal shape for reproducible tests,
6
+ # BUT the published `robotframework-PlatynUI` / `platynui-native` wheels are
7
+ # built WITHOUT the mock feature and raise:
8
+ # ProviderError: Runtime.new_with_mock() requires building with feature 'mock-provider'
9
+ #
10
+ # To actually run this you need a source build of the native package:
11
+ # uv run maturin develop -m packages/native/Cargo.toml --features mock-provider
12
+ #
13
+ # This file shows the query/keyword shape against the mock tree
14
+ # (Mock Application -> "Operations Console" window -> List / Tree / Text /
15
+ # Button "OK" / Button "Cancel"). For an automated, display-free CI check of
16
+ # this skill, rely on the libdoc keyword-fidelity test instead (the runtime is
17
+ # lazy, so libdoc needs no desktop).
18
+ Library PlatynUI.BareMetal use_mock=${True}
19
+
20
+ *** Test Cases ***
21
+ Inspect The Mock Desktop
22
+ [Documentation] Query the deterministic mock tree and assert structure.
23
+ ${windows}= Query //control:Window
24
+ Should Not Be Empty ${windows}
25
+
26
+ # Scope to the mock window, then read an attribute and act on a button.
27
+ Set Root //control:Window[@Name="Operations Console"]
28
+ ${title}= Get Attribute . Name
29
+ Should Be Equal ${title} Operations Console
30
+
31
+ Get Attribute .//control:Button[@Name="OK"] Name == OK
32
+ Highlight .//control:Button[@Name="OK"] duration=${1}
33
+ Pointer Click .//control:Button[@Name="OK"]
@@ -0,0 +1,82 @@
1
+ # PlatynUI CLI & Inspector
2
+
3
+ Two diagnostic tools drive the **locator-development loop**: develop and verify an XPath selector *before* baking it into a test. They are separate packages from the RF library.
4
+
5
+ ```bash
6
+ uv tool install --prerelease allow platynui-cli
7
+ uv tool install --prerelease allow platynui-inspector
8
+ # pip alternative (inside the project venv): pip install --pre platynui-cli platynui-inspector
9
+ ```
10
+
11
+ Prebuilt wheels (no Rust). They talk to the **live desktop** — Linux needs AT-SPI2 running (see `platform-setup.md`).
12
+
13
+ ## platynui-cli
14
+
15
+ Global: `--log-level error|warn|info|debug|trace` (logs → stderr; output → stdout, pipe-safe). Override with `RUST_LOG`.
16
+
17
+ ### Inspect / develop locators (the core loop)
18
+
19
+ ```bash
20
+ platynui-cli list-providers # confirm a provider is active (atspi/uia)
21
+ platynui-cli list-providers --format json
22
+ platynui-cli info # desktop/platform metadata, monitors
23
+
24
+ # Test a selector against the live tree — the main "does my XPath match?" command:
25
+ platynui-cli query "//control:Window"
26
+ platynui-cli query "//control:Button[@Name='OK']"
27
+ platynui-cli query "//control:Button[@Name='OK']/@Bounds" # an attribute
28
+ platynui-cli query "count(//control:Button)" --format json # a value
29
+
30
+ # Dump a subtree to read structure / discover roles & attributes:
31
+ platynui-cli snapshot "//control:Window" --pretty
32
+ platynui-cli snapshot "//control:Window" --format xml --output windows.xml
33
+ platynui-cli snapshot "//control:Window" --max-depth 3 --attrs default
34
+ platynui-cli snapshot "//control:Window" --include "control:Bounds*" "app:*" --no-color
35
+
36
+ # Visually confirm a selector on screen:
37
+ platynui-cli highlight "//control:Button[@Name='OK']" --duration-ms 1200
38
+ platynui-cli highlight --rect "100,100,400,300"
39
+ platynui-cli highlight --clear
40
+
41
+ # Watch live tree events (dynamic UIs), optionally re-running an XPath:
42
+ platynui-cli watch --expression "//control:Window" --limit 5
43
+ ```
44
+
45
+ ### Act (mirror the RF keywords)
46
+
47
+ ```bash
48
+ platynui-cli focus "//control:Button[@Name='New File']"
49
+ platynui-cli screenshot screen.png
50
+ platynui-cli screenshot --rect "0,0,800,600"
51
+
52
+ platynui-cli window --list
53
+ platynui-cli window "//control:Window[@Name='Calculator']" --bring-to-front --wait-ms 500
54
+ platynui-cli window "…" --minimize | --maximize | --restore | --close | --move X Y | --resize W H
55
+
56
+ platynui-cli pointer move "//control:Button[@Name='OK']"
57
+ platynui-cli pointer move --point "10,20"
58
+ platynui-cli pointer click "//control:Button[@Name='OK']" --button left
59
+ platynui-cli pointer multi-click --point "100,200" --count 2
60
+ platynui-cli pointer scroll "0,-3" --expr "//control:List"
61
+ platynui-cli pointer drag --from-expr "//item:ListItem[1]" --to-expr "//item:ListItem[5]"
62
+ platynui-cli pointer position
63
+
64
+ platynui-cli keyboard list # discover valid key names
65
+ platynui-cli keyboard type "Hello <Ctrl+A>" --delay-ms 50
66
+ platynui-cli keyboard press "<Ctrl+S>"
67
+ ```
68
+
69
+ > The **published CLI wheel has no `--mock`** — it always talks to the live desktop. Mock requires a source build with `--features mock-provider`.
70
+
71
+ ## platynui-inspector
72
+
73
+ An egui GUI to explore and debug the live UI tree interactively:
74
+
75
+ - **Left:** hierarchical UI tree (lazy expand, role icons, invalid nodes struck through).
76
+ - **Right:** sortable Properties table (`namespace:name`, value, type) with copy-via-context-menu.
77
+ - **Search bar:** streaming, cancellable XPath evaluation; click a result to reveal it in the tree.
78
+ - Selected elements are **highlighted on screen** (~1.5 s). "Always On Top" toggle.
79
+
80
+ Use it to eyeball the real tree, find the right Role/`@Id`/`@Name`, and test XPath visually; then translate to a keyword call. The CLI `query`/`snapshot`/`highlight` commands are the scriptable equivalent.
81
+
82
+ Run: `platynui-inspector` (needs a display; AT-SPI on Linux). Under WSL2/WSLg, if it crashes with a broken-pipe/winit error, run with `WINIT_UNIX_BACKEND=x11 WAYLAND_DISPLAY= platynui-inspector`.
@@ -0,0 +1,14 @@
1
+ # Installing PlatynUI (preview)
2
+
3
+ Commands are in uv form. For a new environment, Poetry and venv + pip forms, and the general troubleshooting (wrong interpreter, PEP 668, old Python), see `rf-setup` (plugin `rf-core`): `uv add <pkg>` is `poetry add <pkg>` (pip alternative: `.venv/bin/python -m pip install <pkg>`), and `uv run <cmd>` is `poetry run <cmd>` or `.venv/bin/<cmd>`. Versions and floors checked on PyPI 2026-09-26.
4
+
5
+ Package `robotframework-PlatynUI`. The documented `PlatynUI.BareMetal` library exists only as a **pre-release** (Python ≥ 3.12). A plain install resolves the old 0.9.2, which is a different library.
6
+
7
+ ```bash
8
+ uv add robotframework-PlatynUI==0.12.0.dev330 # verified pin # pip: pip install robotframework-PlatynUI==0.12.0.dev330
9
+ uv add --prerelease allow robotframework-PlatynUI # latest pre-release # pip: pip install --pre robotframework-PlatynUI
10
+ ```
11
+
12
+ - The wheel is prebuilt: it bundles the compiled `platynui-native` runtime. No Rust toolchain or git checkout is needed.
13
+ - Linux also needs a running AT-SPI2 accessibility bus and, recommended, an X11 session: see `platform-setup.md`.
14
+ - The optional CLI and inspector are standalone tools: `uv tool install --prerelease allow platynui-cli` and `uv tool install --prerelease allow platynui-inspector` (see `cli-and-inspector.md`).
@@ -0,0 +1,102 @@
1
+ # PlatynUI.BareMetal — Keyword Reference
2
+
3
+ Complete keyword surface of `Library PlatynUI.BareMetal` (verified against `robotframework-PlatynUI==0.12.0.dev330`, library version `0.12.0-dev.330`, scope `SUITE`, doc format `ROBOT`). **24 keywords, all documented.**
4
+
5
+ > The high-level `PlatynUI` library is a placeholder (`Dummy Keyword` only). Use `BareMetal`.
6
+
7
+ ## Import
8
+
9
+ ```robotframework
10
+ Library PlatynUI.BareMetal
11
+ ... keyboard_profile=${None} # KeyboardProfileLike | dict | None
12
+ ... pointer_settings=${None} # PointerSettingsLike | dict | None
13
+ ... pointer_profile=${None} # PointerProfileLike | dict | None
14
+ ... use_mock=${False} # mock provider (needs --features mock-provider build)
15
+ ... auto_activate=${True} # foreground target window before pointer/keyboard
16
+ ```
17
+
18
+ All import args are keyword-only and optional.
19
+
20
+ ## Element references
21
+
22
+ Most keywords take a `descriptor: UiNodeDescriptor` — pass either:
23
+ - a **PlatynUI XPath string** (e.g. `//control:Button[@Name="OK"]`) — auto-converted, lazily resolved with retry (~30 s) until the node appears or `ElementNotFoundError` is raised, or
24
+ - a **`UiNode`** captured from `Query ... only_first=${True}`.
25
+
26
+ Where the signature shows `descriptor: ... | None`, passing `${None}` means "no element" (act on raw coordinates, or type into whatever currently has focus).
27
+
28
+ ## Query & scope
29
+
30
+ | Keyword | Arguments | Returns | Notes |
31
+ |---------|-----------|---------|-------|
32
+ | `Query` | `expression: str`, `root: UiNode \| None = None`, `only_first: bool = False` | node / list / value | Evaluate an XPath expression. `only_first=${True}` → first `UiNode` or `${None}`. Value expressions (`count(...)`) return the computed value. Read-only. |
33
+ | `Set Root` | `descriptor: UiNodeDescriptor \| None` | previous root | Scope subsequent queries to a subtree. `${None}` resets to the desktop. |
34
+
35
+ ## Pointer / mouse
36
+
37
+ Shared optional args (keyword-only `*`): `button: PointerButtonLike = LEFT` (`LEFT`/`MIDDLE`/`RIGHT` or `1`/`2`/`3`), `x`/`y: float | None`, `overrides: PointerOverridesLike | None`, `activate: bool | None` (defaults to library `auto_activate`). See coordinate rules in SKILL.md.
38
+
39
+ | Keyword | Arguments | Short doc |
40
+ |---------|-----------|-----------|
41
+ | `Pointer Click` | `descriptor=None`, `*`, `button=LEFT`, `x=None`, `y=None`, `overrides=None`, `activate=None` | Click at absolute or element-relative screen coordinates. |
42
+ | `Pointer Multi Click` | …above… `+ clicks: int = 2` | Multiple clicks (double=`${2}`, triple=`${3}`). |
43
+ | `Pointer Press` | same as Pointer Click | Press (and hold) a mouse button. |
44
+ | `Pointer Release` | same as Pointer Click | Release a mouse button at current or specified coordinates. |
45
+ | `Pointer Move To` | `descriptor=None`, `*`, `x=None`, `y=None`, `overrides=None`, `activate=None` | Move the pointer (no `button`). |
46
+ | `Get Pointer Position` | `assertion_operator=None`, `assertion_expected=None`, `assertion_message=None` | Current pointer position (assertable). |
47
+
48
+ ## Keyboard
49
+
50
+ | Keyword | Arguments | Short doc |
51
+ |---------|-----------|-----------|
52
+ | `Keyboard Type` | `descriptor: UiNodeDescriptor \| None`, `text: str`, `*`, `overrides: KeyboardOverridesLike \| None = None` | Type a sequence of characters and/or keys (full press→release). |
53
+ | `Keyboard Press` | `descriptor \| None`, `text: str`, `*`, `overrides=None` | Press (and hold) keys. |
54
+ | `Keyboard Release` | `descriptor \| None`, `text: str`, `*`, `overrides=None` | Release keys. |
55
+
56
+ `descriptor` is positional but may be `${None}` (skip focusing). Key syntax: `<Ctrl+A>`, `<Return>`, `<ESC>`, `<Shift+Tab>`, plain text, `${\n}`. List valid key names: `platynui-cli keyboard list`.
57
+
58
+ ## Focus & attributes
59
+
60
+ | Keyword | Arguments | Short doc |
61
+ |---------|-----------|-----------|
62
+ | `Focus` | `descriptor: UiNodeDescriptor` | Set input focus to the element (brings to front + focuses). |
63
+ | `Bring To Front` | `descriptor: UiNodeDescriptor` | Bring the node to the front (no focus). |
64
+ | `Get Attribute` | `descriptor`, `attribute_name: str`, `assertion_operator=None`, `assertion_expected=None`, `assertion_message=None` | Read an attribute (assertable). `ns:Name` selects a namespace. |
65
+
66
+ `Get Attribute` is **assertable** — `Get Attribute //control:Button[@Name="OK"] Name == OK`. Typed/structured attributes expose component aliases (`Bounds.X`, `Bounds.Width`, `ActivationPoint.Y`).
67
+
68
+ ## Window surface
69
+
70
+ All take `descriptor: UiNodeDescriptor` and require a window node (else `PatternError`).
71
+
72
+ | Keyword | Extra args | Short doc |
73
+ |---------|-----------|-----------|
74
+ | `Activate Window` | — | Activate (bring to front and focus) a window. |
75
+ | `Bring To Front` | — | (listed above — front without focus) |
76
+ | `Minimize Window` | — | Minimize a window. |
77
+ | `Maximize Window` | — | Maximize a window. |
78
+ | `Restore Window` | — | Restore from minimized/maximized. |
79
+ | `Close Window` | — | Close a window. |
80
+ | `Move Window` | `x: float`, `y: float` | Move top-left to screen coordinates. |
81
+ | `Resize Window` | `width: float`, `height: float` | Resize. |
82
+ | `Move And Resize Window` | `x`, `y`, `width`, `height` (float) | Move + resize in one operation. |
83
+
84
+ ## Diagnostics
85
+
86
+ | Keyword | Arguments | Short doc |
87
+ |---------|-----------|-----------|
88
+ | `Take Screenshot` | `descriptor=None`, `filename='platynui-screenshot-{index}.png'`, `rect: RectLike \| None = None` | Full screen, an element (its bounds), or a rect. `filename=EMBED` embeds base64 PNG in the log; files go to `${OUTPUT DIR}`; `{index}` auto-increments. |
89
+ | `Highlight` | `descriptor: ... \| list \| None = None`, `*`, `rect: RectLike \| list \| None = None`, `duration: float = 1.0` | Draw an overlay around one/many elements or rect(s) for `duration` seconds. Needs at least one of descriptor/rect. |
90
+
91
+ ## Not present (know the gaps)
92
+
93
+ - **No application launch/attach keyword** — launch with `Library Process` (`Start Process calc.exe`) and locate via `app:Application[...]`.
94
+ - **No explicit wait/retry keyword** — resolution waits automatically (~30 s). There is no runtime keyword to change that timeout.
95
+ - **No semantic action keywords** (`Activate`, `Select`, `Set Value`, `Check`) — these are the *intended direction* of the high-level library, not shipped. Compose `Pointer Click` / `Keyboard Type` / `Query` instead. See `status-and-migration.md`.
96
+
97
+ ## Types referenced
98
+
99
+ - `PointerButtonLike` = `PointerButton` enum (`LEFT=1`, `MIDDLE=2`, `RIGHT=3`) or `int`.
100
+ - `RectLike` = `Rect` | `(x, y, width, height)` tuple | `{x, y, width, height}` dict.
101
+ - `*OverridesLike` / `*ProfileLike` / `*SettingsLike` = native object or a `&{dict}` (keys like `press_delay_ms`, `between_keys_delay_ms`, `acceleration_profile`, `motion`, `jitter_amplitude`, `multi_click_delay_ms`).
102
+ - Exceptions: `BareMetalError` → `ElementNotFoundError`, `ResultTypeError`, `NoQueryError`; native `PlatynUiError` → `PatternError`, `PointerError`, `KeyboardError`, `ProviderError`, …
@@ -0,0 +1,95 @@
1
+ # PlatynUI Locators & Queries
2
+
3
+ PlatynUI's analog of Browser Library's "locators" is an **XPath-2.0 query engine over a normalized desktop UI tree**. Selectors are XPath strings; node names are roles; namespaces scope the query.
4
+
5
+ ## The UI model
6
+
7
+ Every application's accessibility tree is normalized into one model rooted at the **Desktop** document node. Each node exposes:
8
+
9
+ - `role()` — normalized PascalCase role (`Window`, `Button`, `Edit`, `ListItem`…). The original native role is preserved under `native:Role`.
10
+ - `Name` — display name (`@Name`).
11
+ - `Id` — developer-set stable id (`@Id`): UIA AutomationId / AT-SPI accessible_id / macOS AXIdentifier.
12
+ - typed attributes — `Bounds`, `IsVisible`, `IsEnabled`, `IsFocused`, `IsSelected`, `Value`, `Text`, `ActivationPoint`, `ToggleState`, … Structured values auto-expose component aliases: `Bounds.X`, `Bounds.Width`, `ActivationPoint.Y`.
13
+
14
+ Top-level controls appear both directly under the desktop (flat) and under `app:Application` nodes (grouped) — so `app:Application[@Name='Studio']//control:Window` works.
15
+
16
+ ## Namespaces (scope selector)
17
+
18
+ | Prefix | Scope | Examples | Default? |
19
+ |--------|-------|----------|----------|
20
+ | `control` | UI controls | `Window`, `Button`, `Edit`, `Menu`, `Tree`, `Table` | **Yes** |
21
+ | `item` | container children | `ListItem`, `TreeItem`, `TabItem`, `Cell`, `Row` | No |
22
+ | `app` | application/process | `Application` | No |
23
+ | `native` | raw platform attrs | `native:HWND`, `native:Role`, `native:Accessible.*` | No |
24
+
25
+ **The single most important rule:** an unprefixed query matches `control:` only. `//Button` ≡ `//control:Button`. To match container items you MUST write `//item:ListItem` — `//ListItem` finds nothing. Always prefix `app:` and `item:`.
26
+
27
+ ## Supported XPath syntax
28
+
29
+ The engine implements XPath 2.0 over live UI trees (not XML files).
30
+
31
+ **Axes:** `child` (default), `descendant` (`//`), `descendant-or-self`, `self` (`.`), `parent` (`..`), `ancestor`, `ancestor-or-self`, `following`, `following-sibling`, `preceding`, `preceding-sibling`, `attribute` (`@`), `namespace`.
32
+
33
+ **Node tests:** name tests, `*` wildcard, `node()`, `text()`, `comment()`.
34
+
35
+ **Predicates `[...]`:**
36
+ - equality: `[@Name='OK']`, `[@Id="num5Button"]`
37
+ - boolean: `[@Name='Calculator' or @Name='Rechner']`, `and`
38
+ - positional: `[1]`, `[position()=2]`, `last()`
39
+ - functions: `contains()`, `matches()` (regex), `starts-with()`, `count()`, `normalize-space()`, `string()`
40
+ - all-attribute wildcard: `[contains(@*, 'Close')]`
41
+
42
+ **Value expressions** (returned by `Query` as computed values, not nodes): `count(//control:Button)`.
43
+
44
+ Not supported: schema awareness, `fn:unparsed-text*`, static typing.
45
+
46
+ ## Example selectors (from real PlatynUI tests)
47
+
48
+ | Selector | Matches | Notes |
49
+ |----------|---------|-------|
50
+ | `//control:Button[@Name="OK"]` | a button named OK | `control:` optional |
51
+ | `//Button[@Name="New File"]` | same as above unprefixed | default namespace = control |
52
+ | `app:Application[@Name="Notepad"]//Document` | a Document anywhere under Notepad | grouped `app:` view |
53
+ | `app:Application[@Name="ApplicationFrameHost"]/control:Window[@Name="Calculator" or @Name="Rechner"]` | the Calc/Rechner window | direct child `/`, locale-tolerant |
54
+ | `.//control:Button[@Id="num5Button"]` | digit button relative to root | use after `Set Root`; `@Id` stable |
55
+ | `app:Application[@Name='kalk']/Frame//item:TabItem` | a tab item | **`item:` required** |
56
+ | `…/Label[@Name='5']/parent::Button` | the button owning a label | reverse axis |
57
+ | `//*[contains(@Name,'Checked')]` | any node with "Checked" in name | `*` widens past control |
58
+ | `app:Application[@Name='…']//*[contains(@*, 'Close')]` | any node whose any attribute has "Close" | `@*` all-attribute search |
59
+ | `count(//control:Button)` | number of buttons | value expression |
60
+ | `.` | the current root node | with `Query .` |
61
+
62
+ ## Role vocabulary
63
+
64
+ Common normalized roles usable as node names in queries:
65
+
66
+ - **control:** `Window`, `Frame`, `Dialog`, `Button`, `CheckBox`, `ComboBox`, `Edit`, `Text`, `List`, `Tree`, `Table`, `Menu`, `MenuBar`, `MenuItem`, `TabList`, `Document`, `Label`, `Control`.
67
+ - **item:** `ListItem`, `TreeItem`, `TabItem`, `Cell`, `EditableCell`, `Row`.
68
+ - **app:** `Application`.
69
+ - **special:** `Desktop` (root).
70
+
71
+ Cross-platform normalization (originals under `native:Role`):
72
+
73
+ | PlatynUI | UIA | AT-SPI2 | macOS AX |
74
+ |----------|-----|---------|----------|
75
+ | Button | Button | PUSH_BUTTON | AXButton |
76
+ | Edit | Edit | ENTRY/TEXT | AXTextField |
77
+ | List / ListItem | List / ListItem | LIST / LIST_ITEM | AXList / AXStaticText |
78
+ | Tree / TreeItem | Tree / TreeItem | TREE / TABLE_ROW | AXOutline / AXRow |
79
+ | Menu / MenuItem | Menu / MenuItem | MENU / MENU_ITEM | AXMenu / AXMenuItem |
80
+ | TabList / TabItem | Tab / TabItem | PAGE_TAB_LIST / PAGE_TAB | AXTabGroup / AXRadioButton |
81
+ | Window | Window | FRAME / WINDOW | AXWindow |
82
+
83
+ ## Locator strategy (best practices)
84
+
85
+ 1. **`control` is default** — only add `control:` for clarity.
86
+ 2. **Always prefix `app:` and `item:`** — the #1 "element not found" cause.
87
+ 3. **Prefer `@Id` over `@Name`** — language-independent and stable; `@Name` only when no Id.
88
+ 4. **Anchor on the app, then descend** — `app:Application[@Name='…']//control:Window//control:Button[@Id='…']`, or `Set Root` once and use `.//…`.
89
+ 5. **`/` vs `//` deliberately** — `/` direct child (precise/fast), `//` any descendant (broad/slower).
90
+ 6. **Localization → `or`** — `[@Name='Calculator' or @Name='Rechner']`.
91
+ 7. **Fuzzy → functions** — `contains(@Name,'…')`, `matches(@X,'regex')`, `[contains(@*,'…')]`.
92
+ 8. **Structure → axes** — `…/Label[@Name='5']/parent::Button`.
93
+ 9. **Positional `[1]` is a last resort** — brittle; prefer attribute predicates.
94
+ 10. **Don't `Sleep`** — descriptor resolution retries ~30 s; write the right selector and let it wait.
95
+ 11. **Develop selectors with the CLI/inspector** — `platynui-cli query "…"`, `platynui-cli highlight "…"`, or the inspector GUI (see `cli-and-inspector.md`).