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.
- 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 +113 -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/async-jobs.md +42 -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/loose-assertions.md +20 -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 +120 -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/loose-assertions.md +18 -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 +13 -0
- robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +120 -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 +445 -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 +128 -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 +517 -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 +119 -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 +123 -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 +10 -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 +268 -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 +134 -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/selector-drift.md +29 -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 +320 -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.dist-info/METADATA +198 -0
- robotframework_plugins-2026.11.0.dist-info/RECORD +199 -0
- robotframework_plugins-2026.11.0.dist-info/WHEEL +4 -0
- robotframework_plugins-2026.11.0.dist-info/entry_points.txt +2 -0
- 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"]
|
robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md
ADDED
|
@@ -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`).
|