robotframework-plugins 2026.11.0.dev1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- robotframework_plugins/__init__.py +14 -0
- robotframework_plugins/_assets/catalog.json +143 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
- robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +110 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
- robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
- robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
- robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
- robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
- robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
- robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
- robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
- robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
- robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
- robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
- robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
- robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
- robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
- robotframework_plugins/_assets.py +120 -0
- robotframework_plugins/_catalog.py +123 -0
- robotframework_plugins/_snapshot.py +230 -0
- robotframework_plugins/adapters/__init__.py +53 -0
- robotframework_plugins/adapters/_base.py +400 -0
- robotframework_plugins/adapters/claude_code.py +312 -0
- robotframework_plugins/adapters/claude_desktop.py +129 -0
- robotframework_plugins/adapters/codex.py +276 -0
- robotframework_plugins/adapters/copilot.py +87 -0
- robotframework_plugins/adapters/cursor.py +295 -0
- robotframework_plugins/adapters/goose.py +240 -0
- robotframework_plugins/adapters/opencode.py +170 -0
- robotframework_plugins/bundle.py +85 -0
- robotframework_plugins/cli.py +1311 -0
- robotframework_plugins/detect.py +121 -0
- robotframework_plugins/manifest.py +338 -0
- robotframework_plugins/py.typed +0 -0
- robotframework_plugins/skillzip.py +39 -0
- robotframework_plugins/transforms.py +725 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Migrates Robot Framework projects. Use when upgrading Robot Framework, replacing legacy syntax such as Run Keyword If or [Return], or moving from SeleniumLibrary to Browser or RequestsLibrary to RESTinstance. Works in phases and reports each file as migrated or unverified."
|
|
3
|
+
mode: subagent
|
|
4
|
+
permission:
|
|
5
|
+
edit: allow
|
|
6
|
+
bash: allow
|
|
7
|
+
---
|
|
8
|
+
<!-- Generated by scripts/build-agent-variants.py from plugins/rf-core/agents/rf-migration-guide.md. Do not edit. -->
|
|
9
|
+
|
|
10
|
+
# Robot Framework Migration Guide
|
|
11
|
+
|
|
12
|
+
You plan and carry out migrations of Robot Framework projects: RF version upgrades,
|
|
13
|
+
legacy-syntax modernization and library switches. You work in phases, verify every
|
|
14
|
+
file with deterministic checks, and report a file as migrated only when the checks
|
|
15
|
+
are clean. The legacy → modern syntax mapping lives in the `rf-language` skill
|
|
16
|
+
(`references/migration.md`: construct, replacement, minimum RF version, Robocop rule).
|
|
17
|
+
|
|
18
|
+
## Syntax migration procedure (agent-owned)
|
|
19
|
+
|
|
20
|
+
1. **Inventory.** Count deprecated syntax per rule and file:
|
|
21
|
+
`robocop check --no-cache --select "DEPR*" --reports rules_by_id tests resources`.
|
|
22
|
+
Add the error check `robocop check --no-cache --threshold E tests resources`.
|
|
23
|
+
When the target RF version differs from the installed one, pass it:
|
|
24
|
+
`robocop check --no-cache --target-version 7 --select "DEPR*" tests resources`.
|
|
25
|
+
Select several rule groups by repeating `--select`; a comma list
|
|
26
|
+
(`DEPR*` and `ERR*` in one value) matches no rule and reports "No issues found".
|
|
27
|
+
The `rf_conventions` report of `rf-language` adds the legacy constructs Robocop does not flag.
|
|
28
|
+
2. **Phased plan.** Migrate shared resources first, then suites from the least to the
|
|
29
|
+
most dependent. Never migrate everything at once.
|
|
30
|
+
3. **Per-file fixes.** Rewrite one file at a time with the `rf-language` migration
|
|
31
|
+
table, then re-run the checks on that file. Robocop's `--fix` may apply the
|
|
32
|
+
mechanical rewrites, but only on a clean git working tree, followed by a review of
|
|
33
|
+
the diff.
|
|
34
|
+
4. **Exit check.** A file is migrated when it has zero `DEPR` findings, zero
|
|
35
|
+
error-severity findings, and `robotcode analyze code` reports no errors for the
|
|
36
|
+
suites that use it.
|
|
37
|
+
|
|
38
|
+
Without Robocop, say that deterministic verification is unavailable, point to
|
|
39
|
+
`rf-setup` to add `robotcode[all]` (which includes Robocop) as a dev dependency, count legacy
|
|
40
|
+
constructs with the `rf_conventions` report the `rf-language` skill documents, and report the migration status as **unverified**.
|
|
41
|
+
|
|
42
|
+
## Library migrations
|
|
43
|
+
|
|
44
|
+
The keyword tables for a library switch live in the target library's skill: SeleniumLibrary → Browser in `rf-browser` (plugin `rf-web`, `references/migrate-from-selenium.md`), RequestsLibrary → RESTinstance in `rf-restinstance` (plugin `rf-api`, `references/migrate-from-requests.md`). Use the same phases as for syntax: import both libraries during the transition, move shared keywords first, then suites one by one, and remove the old import last.
|
|
45
|
+
|
|
46
|
+
When the target library's skill is not available, say which plugin ships it and suggest installing that plugin before you change any library-specific code; don't continue from memory.
|
|
47
|
+
|
|
48
|
+
## Routing
|
|
49
|
+
|
|
50
|
+
| Work | Skill |
|
|
51
|
+
|------|-------|
|
|
52
|
+
| Legacy → modern syntax table, `rf_conventions` legacy counts | `rf-language` (`references/migration.md`) |
|
|
53
|
+
| Python libraries and listeners to modernize | `rf-python-library` |
|
|
54
|
+
| Keyword existence and arguments of the target library | `robotcode doc keyword <Library> "<Keyword>"` |
|
|
55
|
+
| Browser, SeleniumLibrary specifics; SeleniumLibrary → Browser table | `rf-browser` / `rf-selenium` (plugin `rf-web`) |
|
|
56
|
+
| RESTinstance, RequestsLibrary specifics; RequestsLibrary → RESTinstance table | `rf-restinstance` / `rf-requests` (plugin `rf-api`) |
|
|
57
|
+
| AppiumLibrary 3.x removed keywords | `rf-appium` (plugin `rf-mobile`) |
|
|
58
|
+
| Installing robotcode (with Robocop) or the new library | `rf-setup` |
|
|
59
|
+
| Reading results after the migrated run | `robotcode results show --failed` (robotcode plugin) |
|
|
60
|
+
|
|
61
|
+
## Verification loop
|
|
62
|
+
|
|
63
|
+
For every `.robot`, `.resource` or Python library file you write or change:
|
|
64
|
+
|
|
65
|
+
1. Write the change.
|
|
66
|
+
2. Confirm keyword names and arguments with `robotcode doc keyword <Library> "<Keyword>"` (candidates: `robotcode doc keywords <Library> "<text>"`).
|
|
67
|
+
3. Run `robotcode analyze code <changed files>` and fix every error. It runs nothing, so it misses undefined variables set at run time, a space before `=` in named arguments, embedded-argument mismatches and union-with-`str` conversions; the real run in step 5 catches them.
|
|
68
|
+
4. Run `robocop check --no-cache` on the changed files for deprecated syntax (select several rule groups by repeating `--select`, never with a comma list).
|
|
69
|
+
5. Run the affected tests by longname, `robotcode robot -bl "<Suite.Sub.Test>"` (longnames from `robotcode discover tests`), or a whole directory, never a single `.robot` file.
|
|
70
|
+
6. Read failures with `robotcode results show --failed` and `robotcode results log -bl "<longname>"`.
|
|
71
|
+
|
|
72
|
+
## Constraints
|
|
73
|
+
|
|
74
|
+
- Always propose a phased plan; old and new code coexist during the transition.
|
|
75
|
+
- Report per file: findings before, findings after, dry-run result.
|
|
76
|
+
- Never claim a migration is complete without a clean exit check.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Designs Robot Framework test projects. Use when starting a test automation project, choosing Browser or SeleniumLibrary, RequestsLibrary or RESTinstance, or restructuring suites, resources and environments. Returns the library choice with reasons, the layout and keyword layers, then writes them."
|
|
3
|
+
mode: subagent
|
|
4
|
+
permission:
|
|
5
|
+
edit: allow
|
|
6
|
+
bash: allow
|
|
7
|
+
---
|
|
8
|
+
<!-- Generated by scripts/build-agent-variants.py from plugins/rf-core/agents/rf-test-architect.md. Do not edit. -->
|
|
9
|
+
|
|
10
|
+
# Robot Framework Test Architect
|
|
11
|
+
|
|
12
|
+
You design Robot Framework test automation projects: which libraries to use, how the
|
|
13
|
+
project is laid out, and how keywords are layered. You decide the architecture yourself
|
|
14
|
+
and hand the writing of suites, keywords and libraries to the skills listed under
|
|
15
|
+
Routing. Load a skill before you write the part it owns; do not write from memory.
|
|
16
|
+
|
|
17
|
+
## What this agent decides (agent-owned)
|
|
18
|
+
|
|
19
|
+
### Web library selection
|
|
20
|
+
|
|
21
|
+
Choose **Browser** (`rf-browser` in plugin `rf-web`, the default for new web tests) when the project needs
|
|
22
|
+
Playwright features: auto-waiting, network interception, shadow DOM or iframes through
|
|
23
|
+
selectors, several browser contexts, or the built-in assertion engine.
|
|
24
|
+
|
|
25
|
+
Choose **SeleniumLibrary** (`rf-selenium` in plugin `rf-web`) when the team already runs Selenium or a
|
|
26
|
+
WebDriver grid / cloud service, depends on Selenium plugins, or must keep existing
|
|
27
|
+
SeleniumLibrary suites.
|
|
28
|
+
|
|
29
|
+
### API library selection
|
|
30
|
+
|
|
31
|
+
Choose **RequestsLibrary** (`rf-requests` in plugin `rf-api`, the default for API tests) for explicit HTTP
|
|
32
|
+
control: sessions, form data, file uploads, XML, and assertions on the response object.
|
|
33
|
+
|
|
34
|
+
Choose **RESTinstance** (`rf-restinstance` in plugin `rf-api`) when JSON Schema or OpenAPI contract checks
|
|
35
|
+
are central and typed field assertions (`Integer`, `String`) fit the responses.
|
|
36
|
+
|
|
37
|
+
### Project layout
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
project/
|
|
41
|
+
tests/ # suites by area: web/, api/, mobile/, e2e/
|
|
42
|
+
resources/ # common.resource (library imports) + one <domain>.resource per domain
|
|
43
|
+
libraries/ # project Python keyword libraries (on the python-path)
|
|
44
|
+
variables/ # per-environment variables: dev.yaml, staging.yaml, common.py
|
|
45
|
+
data/ # test data files (CSV, JSON)
|
|
46
|
+
results/ # output directory
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Reuse an existing resource directory (`resources/`, `keywords/` or `res/`) and never
|
|
50
|
+
overwrite existing files. Installing Robot Framework and libraries, `robot.toml` and the
|
|
51
|
+
python-path belong to `rf-setup`.
|
|
52
|
+
|
|
53
|
+
### Keyword abstraction layers
|
|
54
|
+
|
|
55
|
+
1. Test cases read as business steps ("User Can Complete Purchase").
|
|
56
|
+
2. Business keywords in domain resources ("Add Item To Cart", "Complete Checkout").
|
|
57
|
+
3. Technical keywords wrap library calls (a click, filling a form field, an HTTP request).
|
|
58
|
+
|
|
59
|
+
## Routing
|
|
60
|
+
|
|
61
|
+
| Work | Skill |
|
|
62
|
+
|------|-------|
|
|
63
|
+
| Suites, test cases, `__init__.robot`, tags, templates, user keywords, resource and variable files | `rf-language` |
|
|
64
|
+
| Project keyword libraries and listeners in Python (`libraries/*.py`), checked with its library checker | `rf-python-library` |
|
|
65
|
+
| Installing RF and libraries, project layout mechanics, `robot.toml`, python-path | `rf-setup` |
|
|
66
|
+
| Web tests with Browser / SeleniumLibrary | `rf-browser` / `rf-selenium` (plugin `rf-web`) |
|
|
67
|
+
| API tests with RequestsLibrary / RESTinstance | `rf-requests` / `rf-restinstance` (plugin `rf-api`) |
|
|
68
|
+
| Mobile tests | `rf-appium` (plugin `rf-mobile`) |
|
|
69
|
+
| Desktop tests | `rf-platynui` (plugin `rf-desktop`) |
|
|
70
|
+
| Keyword names and arguments | `robotcode doc keyword <Library> "<Keyword>"` |
|
|
71
|
+
| Running, reading results, stepping through a test | `robotcode robot -bl`, `robotcode results`, `robotcode robot-debug` (robotcode plugin) |
|
|
72
|
+
|
|
73
|
+
A library skill ships in a technology plugin that may not be installed. When the one you need is not available, name its plugin and suggest installing it; don't continue from memory for library-specific details.
|
|
74
|
+
|
|
75
|
+
## Workflow
|
|
76
|
+
|
|
77
|
+
1. Gather requirements: application under test, team skills, CI environment, coverage goals.
|
|
78
|
+
2. Select the libraries with the criteria above and state the reason.
|
|
79
|
+
3. Propose the layout and the keyword layers; list the files you will create.
|
|
80
|
+
4. Write the suites and resources with `rf-language`, the Python libraries with
|
|
81
|
+
`rf-python-library`, and the library calls with the matching library skill.
|
|
82
|
+
5. Verify with the loop below before handing the project over.
|
|
83
|
+
|
|
84
|
+
## Verification loop
|
|
85
|
+
|
|
86
|
+
For every `.robot`, `.resource` or Python library file you write or change:
|
|
87
|
+
|
|
88
|
+
1. Write the change.
|
|
89
|
+
2. Confirm keyword names and arguments with `robotcode doc keyword <Library> "<Keyword>"` (candidates: `robotcode doc keywords <Library> "<text>"`).
|
|
90
|
+
3. Run `robotcode analyze code <changed files>` and fix every error. It runs nothing, so it misses undefined variables set at run time, a space before `=` in named arguments, embedded-argument mismatches and union-with-`str` conversions; the real run in step 5 catches them.
|
|
91
|
+
4. Run `robocop check --no-cache` on the changed files for deprecated syntax (select several rule groups by repeating `--select`, never with a comma list).
|
|
92
|
+
5. Run the affected tests by longname, `robotcode robot -bl "<Suite.Sub.Test>"` (longnames from `robotcode discover tests`), or a whole directory, never a single `.robot` file.
|
|
93
|
+
6. Read failures with `robotcode results show --failed` and `robotcode results log -bl "<longname>"`.
|
|
94
|
+
|
|
95
|
+
## Constraints
|
|
96
|
+
|
|
97
|
+
- Write Robot Framework 7 syntax; the skills show the modern forms.
|
|
98
|
+
- Keep control structures out of test bodies; put logic into keywords.
|
|
99
|
+
- No `Sleep` for synchronization; use the library's waiting mechanism.
|
|
100
|
+
- Never overwrite existing project files; extend them.
|
|
101
|
+
- Name the library and the reason for every library choice in your plan.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// rf-agentskills hooks for OpenCode.
|
|
2
|
+
// Generated by scripts/build-agent-variants.py from plugins/rf-core/hooks/hooks.json. Do not edit.
|
|
3
|
+
//
|
|
4
|
+
// OpenCode has no Claude-style hooks.json; plugins are JS modules. This one runs
|
|
5
|
+
// the same hook scripts as the other agents, from ../rf-core-files/scripts/
|
|
6
|
+
// next to this file (the installer puts both there, project or user scope):
|
|
7
|
+
//
|
|
8
|
+
// tool.execute.after edits of .robot/.resource files -> validate_robot.mjs;
|
|
9
|
+
// bash output -> rf_error_hints.mjs; findings and hints
|
|
10
|
+
// are appended to the tool output.
|
|
11
|
+
// session.created -> check_rf_environment.mjs; its report is appended to the
|
|
12
|
+
// session's first tool output (OpenCode cannot inject
|
|
13
|
+
// text at session start).
|
|
14
|
+
//
|
|
15
|
+
// Not ported (no OpenCode event can inject text at that point):
|
|
16
|
+
// Stop * -> maybe_remind_robot_tests.mjs
|
|
17
|
+
// Stop * -> report_pending_errors.mjs
|
|
18
|
+
// Stop * -> validate_robot_project.mjs
|
|
19
|
+
// UserPromptSubmit * -> maybe_inject_rf_context.mjs
|
|
20
|
+
import { spawnSync } from "node:child_process";
|
|
21
|
+
import { existsSync } from "node:fs";
|
|
22
|
+
import { fileURLToPath } from "node:url";
|
|
23
|
+
|
|
24
|
+
const SCRIPTS = fileURLToPath(new URL("../rf-core-files/scripts/", import.meta.url));
|
|
25
|
+
const EDIT_SCRIPT = "validate_robot.mjs";
|
|
26
|
+
const SHELL_SCRIPT = "rf_error_hints.mjs";
|
|
27
|
+
const SESSION_SCRIPT = "check_rf_environment.mjs";
|
|
28
|
+
const TIMEOUT_MS = 60000;
|
|
29
|
+
const EDIT_TOOLS = { edit: "Edit", write: "Write", multiedit: "MultiEdit", patch: "apply_patch", apply_patch: "apply_patch" };
|
|
30
|
+
|
|
31
|
+
/** Run a hook script with Claude-shaped stdin; return the text it reports, or "". */
|
|
32
|
+
export function runHook(script, payload) {
|
|
33
|
+
const path = SCRIPTS + script;
|
|
34
|
+
if (!script || !existsSync(path)) return "";
|
|
35
|
+
const r = spawnSync("node", [path], {
|
|
36
|
+
input: JSON.stringify(payload), encoding: "utf-8", timeout: TIMEOUT_MS, windowsHide: true,
|
|
37
|
+
env: { ...process.env, TOOL_INPUT: "" },
|
|
38
|
+
});
|
|
39
|
+
if (r.error || r.status === null) return "";
|
|
40
|
+
if (r.status === 2) return (r.stderr ?? "").trim();
|
|
41
|
+
try {
|
|
42
|
+
return JSON.parse(r.stdout || "null")?.hookSpecificOutput?.additionalContext ?? "";
|
|
43
|
+
} catch {
|
|
44
|
+
return "";
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export const RfAgentSkills = async ({ directory }) => {
|
|
49
|
+
const pendingArgs = new Map(); // callID -> tool args (tool.execute.after has none)
|
|
50
|
+
const sessionReports = new Map(); // sessionID -> environment report not yet shown
|
|
51
|
+
|
|
52
|
+
const append = (output, text) => {
|
|
53
|
+
if (text) output.output = `${output.output ?? ""}\n\n${text}`;
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
return {
|
|
57
|
+
"tool.execute.before": async (input, output) => {
|
|
58
|
+
if (EDIT_TOOLS[input.tool] || input.tool === "bash") pendingArgs.set(input.callID, output.args ?? {});
|
|
59
|
+
},
|
|
60
|
+
"tool.execute.after": async (input, output) => {
|
|
61
|
+
const report = sessionReports.get(input.sessionID);
|
|
62
|
+
if (report) {
|
|
63
|
+
sessionReports.delete(input.sessionID);
|
|
64
|
+
append(output, report);
|
|
65
|
+
}
|
|
66
|
+
if (input.tool === "bash") {
|
|
67
|
+
append(output, runHook(SHELL_SCRIPT, {
|
|
68
|
+
hook_event_name: "PostToolUse", session_id: input.sessionID, cwd: directory,
|
|
69
|
+
tool_name: "Bash", tool_input: pendingArgs.get(input.callID) ?? {},
|
|
70
|
+
tool_response: String(output.output ?? ""),
|
|
71
|
+
}));
|
|
72
|
+
pendingArgs.delete(input.callID);
|
|
73
|
+
return;
|
|
74
|
+
}
|
|
75
|
+
const toolName = EDIT_TOOLS[input.tool];
|
|
76
|
+
if (!toolName) return;
|
|
77
|
+
const args = pendingArgs.get(input.callID) ?? {};
|
|
78
|
+
pendingArgs.delete(input.callID);
|
|
79
|
+
const toolInput = { ...args };
|
|
80
|
+
if (typeof args.patchText === "string") toolInput.input = args.patchText;
|
|
81
|
+
append(output, runHook(EDIT_SCRIPT, {
|
|
82
|
+
hook_event_name: "PostToolUse", session_id: input.sessionID, cwd: directory,
|
|
83
|
+
tool_name: toolName, tool_input: toolInput,
|
|
84
|
+
}));
|
|
85
|
+
},
|
|
86
|
+
event: async ({ event }) => {
|
|
87
|
+
if (event?.type !== "session.created") return;
|
|
88
|
+
const id = event.properties?.info?.id ?? event.properties?.sessionID;
|
|
89
|
+
const text = runHook(SESSION_SCRIPT, { hook_event_name: "SessionStart", session_id: id, cwd: directory });
|
|
90
|
+
if (id && text) sessionReports.set(id, text);
|
|
91
|
+
},
|
|
92
|
+
};
|
|
93
|
+
};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "rf-desktop",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "PlatynUI skill for Robot Framework desktop UI tests.",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "manykarim",
|
|
7
|
+
"email": "manykarim@users.noreply.github.com"
|
|
8
|
+
},
|
|
9
|
+
"homepage": "https://github.com/MarketSquare/robotframework-plugins",
|
|
10
|
+
"repository": "https://github.com/MarketSquare/robotframework-plugins",
|
|
11
|
+
"license": "Apache-2.0",
|
|
12
|
+
"keywords": [
|
|
13
|
+
"robotframework",
|
|
14
|
+
"testing",
|
|
15
|
+
"desktop-testing",
|
|
16
|
+
"platynui"
|
|
17
|
+
],
|
|
18
|
+
"dependencies": [
|
|
19
|
+
{
|
|
20
|
+
"name": "rf-core",
|
|
21
|
+
"version": "^1.0"
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
The `rf-desktop` plugin, versioned on its own (`rf-desktop--v<version>` tags); see `RELEASING.md` at the repository root.
|
|
4
|
+
|
|
5
|
+
## 1.0.0 (unreleased)
|
|
6
|
+
|
|
7
|
+
First release, split out of `rf-agentskills` 3.0.0: `rf-platynui`. It depends on `rf-core` `^1.0`. Skill names are unchanged; their plugin prefix is now `rf-desktop:` instead of `rf-agentskills:`, for example `/rf-desktop:rf-platynui`.
|
|
8
|
+
|
|
9
|
+
- **Install steps moved here** from `rf-setup`: `rf-platynui` has `references/install.md`, with the pre-release pin.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# rf-desktop plugin
|
|
2
|
+
|
|
3
|
+
Robot Framework skills for desktop tests. Install instructions for every agent are in the [repository README](https://github.com/MarketSquare/robotframework-plugins#install).
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
/plugin install rf-desktop --marketplace MarketSquare/robotframework-plugins
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
That one step works on Claude Code 2.1.275 or later. The commands for other agents and older versions are in the repository README.
|
|
12
|
+
|
|
13
|
+
| Skill | Library and package |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `rf-platynui` | PlatynUI: `robotframework-PlatynUI` |
|
|
16
|
+
|
|
17
|
+
## Needs rf-core
|
|
18
|
+
|
|
19
|
+
This plugin depends on `rf-core`, which holds Robot Framework syntax, environment setup, the subagents and the validation hooks. Claude Code installs `rf-core` with it. Copilot CLI and Codex don't install plugin dependencies, so install `rf-core` there too:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
copilot plugin install rf-core@robotframework-plugins
|
|
23
|
+
codex plugin add rf-core@robotframework-plugins
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The `robotframework-plugins` installer adds `rf-core` for you. Don't install this plugin next to the `rf-agentskills` bundle: the bundle carries its own copy of every skill, and you would see each skill twice.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Programme manifest: see schemas/catalog.schema.json and CONTRIBUTING.md.
|
|
2
|
+
name: rf-desktop
|
|
3
|
+
summary: PlatynUI skill for desktop UI tests.
|
|
4
|
+
tier: verified
|
|
5
|
+
status: active
|
|
6
|
+
maintainers:
|
|
7
|
+
- github: manykarim
|
|
8
|
+
name: Many Kasiriha
|
|
9
|
+
libraries:
|
|
10
|
+
- name: PlatynUI
|
|
11
|
+
package: robotframework-PlatynUI
|
|
12
|
+
versions: ">=0.12.0.dev0"
|
|
13
|
+
skills: [rf-platynui]
|
|
14
|
+
robotframework: ">=7.0"
|
|
15
|
+
agents:
|
|
16
|
+
- claude-code
|
|
17
|
+
- copilot-cli
|
|
18
|
+
- vscode-copilot
|
|
19
|
+
- codex
|
|
20
|
+
- cursor
|
|
21
|
+
- opencode
|
|
22
|
+
- goose
|
|
23
|
+
- claude-desktop
|
|
@@ -0,0 +1,266 @@
|
|
|
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
|
+
## Essential Concepts
|
|
78
|
+
|
|
79
|
+
### The normalized desktop UI model
|
|
80
|
+
|
|
81
|
+
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`.
|
|
82
|
+
|
|
83
|
+
### Four query namespaces
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
control: UI controls (Window, Button, Edit, …) ← DEFAULT (unprefixed = control:)
|
|
87
|
+
item: container children (ListItem, TreeItem, TabItem, Cell, Row)
|
|
88
|
+
app: Application/process nodes
|
|
89
|
+
native: raw platform attributes (native:HWND, native:Role, …)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**Critical rule:** an unprefixed query matches `control:` **only**. You MUST prefix `app:` and `item:` explicitly — `//ListItem` finds nothing; `//item:ListItem` works.
|
|
93
|
+
|
|
94
|
+
### XPath query language
|
|
95
|
+
|
|
96
|
+
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}`.
|
|
97
|
+
|
|
98
|
+
```robotframework
|
|
99
|
+
Pointer Click //control:Button[@Name="OK"]
|
|
100
|
+
Pointer Click app:Application[@Name="Calculator"]//Button[@Id="num5Button"]
|
|
101
|
+
${count}= Query count(//control:Button) # value expression
|
|
102
|
+
${node}= Query //control:Edit[@Name="Search"] only_first=${True}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
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`.
|
|
106
|
+
|
|
107
|
+
### Lazy resolution with built-in wait
|
|
108
|
+
|
|
109
|
+
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`.
|
|
110
|
+
|
|
111
|
+
### Coordinate semantics (pointer keywords)
|
|
112
|
+
|
|
113
|
+
| You pass | Behavior |
|
|
114
|
+
|----------|----------|
|
|
115
|
+
| descriptor, no x/y | acts at the element's `ActivationPoint` (else bounds center) |
|
|
116
|
+
| descriptor **+** x/y | x/y are **offsets** from the element's top-left bounds |
|
|
117
|
+
| no descriptor, x/y | x/y are **absolute screen** coordinates |
|
|
118
|
+
| only one of x/y | `ValueError` — pass both together |
|
|
119
|
+
|
|
120
|
+
### Window keywords need a window node
|
|
121
|
+
|
|
122
|
+
`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`.
|
|
123
|
+
|
|
124
|
+
## Core Keywords Quick Reference
|
|
125
|
+
|
|
126
|
+
### Query & scope
|
|
127
|
+
|
|
128
|
+
```robotframework
|
|
129
|
+
${node}= Query //control:Button[@Name="OK"] only_first=${True}
|
|
130
|
+
${all}= Query //item:ListItem # list of nodes
|
|
131
|
+
${n}= Query count(//control:Button) # computed value
|
|
132
|
+
Set Root app:Application[@Name="Calculator"]//control:Window # scope later queries
|
|
133
|
+
Set Root ${None} # reset to desktop
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Pointer / mouse
|
|
137
|
+
|
|
138
|
+
```robotframework
|
|
139
|
+
Pointer Click //control:Button[@Name="OK"]
|
|
140
|
+
Pointer Click //control:Button[@Name="OK"] button=RIGHT activate=${False}
|
|
141
|
+
Pointer Multi Click //item:ListItem[@Name="file.txt"] clicks=${2}
|
|
142
|
+
Pointer Move To ${None} x=${100} y=${200} # absolute screen
|
|
143
|
+
Pointer Press //control:Slider
|
|
144
|
+
Pointer Release ${None}
|
|
145
|
+
${pos}= Get Pointer Position
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Keyboard
|
|
149
|
+
|
|
150
|
+
```robotframework
|
|
151
|
+
Keyboard Type //control:Edit[@Name="Search"] Hello <Ctrl+A> world${\n}
|
|
152
|
+
Keyboard Type ${None} <Ctrl+A><Delete> # type into whatever has focus
|
|
153
|
+
Keyboard Press ${None} <Shift>
|
|
154
|
+
Keyboard Release ${None} <Shift>
|
|
155
|
+
```
|
|
156
|
+
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`.
|
|
157
|
+
|
|
158
|
+
### Focus, attributes, windows
|
|
159
|
+
|
|
160
|
+
```robotframework
|
|
161
|
+
Focus //control:Button[@Name="New File"]
|
|
162
|
+
${bounds}= Get Attribute //control:Window[@Name="Calc"] Bounds
|
|
163
|
+
Get Attribute //control:Button[@Name="OK"] Name == OK # built-in assertion
|
|
164
|
+
Bring To Front //control:Window[@Name="Calc"]
|
|
165
|
+
Activate Window //control:Window[@Name="Calc"]
|
|
166
|
+
Maximize Window //control:Window[@Name="Calc"]
|
|
167
|
+
Move And Resize Window //control:Window[@Name="Calc"] ${0} ${0} ${800} ${600}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Diagnostics
|
|
171
|
+
|
|
172
|
+
```robotframework
|
|
173
|
+
Take Screenshot # full screen → ${OUTPUT DIR}
|
|
174
|
+
Take Screenshot //control:Window[@Name="Calc"] # just the element
|
|
175
|
+
Take Screenshot filename=EMBED # inline base64 in the log
|
|
176
|
+
Highlight //control:Button[@Name="OK"] duration=${2} # draw an overlay (debug)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Locator Strategy
|
|
180
|
+
|
|
181
|
+
1. **Default namespace is `control`** — `//Button` ≡ `//control:Button`. Add `control:` only for clarity.
|
|
182
|
+
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."
|
|
183
|
+
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.
|
|
184
|
+
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='…']`).
|
|
185
|
+
5. **Handle localization with `or`** — `[@Name='Calculator' or @Name='Rechner']`.
|
|
186
|
+
6. **Fuzzy match with functions** — `contains(@Name,'Save')`, `matches(@Name,'.*Save.*')`, `[contains(@*,'Close')]` (search across all attributes).
|
|
187
|
+
7. **Step axes when structure beats identity** — `…/Label[@Name='5']/parent::Button`.
|
|
188
|
+
8. **Let resolution wait** — don't `Sleep`; the descriptor retries for ~30 s.
|
|
189
|
+
|
|
190
|
+
## Common Patterns
|
|
191
|
+
|
|
192
|
+
### Launch an app, scope to it, act
|
|
193
|
+
|
|
194
|
+
```robotframework
|
|
195
|
+
*** Settings ***
|
|
196
|
+
Library PlatynUI.BareMetal
|
|
197
|
+
Library Process
|
|
198
|
+
Test Setup Start Calculator
|
|
199
|
+
|
|
200
|
+
*** Keywords ***
|
|
201
|
+
Start Calculator
|
|
202
|
+
Start Process calc.exe
|
|
203
|
+
# Prefer letting the next Query wait over a fixed Sleep.
|
|
204
|
+
|
|
205
|
+
Enter Digit
|
|
206
|
+
[Arguments] ${d}
|
|
207
|
+
Set Root app:Application[@Name="ApplicationFrameHost"]/control:Window[@Name="Calculator" or @Name="Rechner"]
|
|
208
|
+
Pointer Click .//control:Button[@Id="num${d}Button"]
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Type into a field and assert
|
|
212
|
+
|
|
213
|
+
```robotframework
|
|
214
|
+
Keyboard Type //control:Edit[@Name="Search"] robot framework${\n}
|
|
215
|
+
Get Attribute //control:Edit[@Name="Search"] Value == robot framework
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Verify targeting before automating
|
|
219
|
+
|
|
220
|
+
```robotframework
|
|
221
|
+
${node}= Query //control:Button[@Name="Submit"] only_first=${True}
|
|
222
|
+
Highlight ${node} duration=${2} # visually confirm you matched the right node
|
|
223
|
+
Pointer Click ${node}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## CLI Tooling (locator development loop)
|
|
227
|
+
|
|
228
|
+
Develop and debug selectors with `platynui-cli` before baking them into tests:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
platynui-cli list-providers # confirm a provider is active
|
|
232
|
+
platynui-cli query "//control:Button[@Name='OK']" # test a selector live
|
|
233
|
+
platynui-cli snapshot "//control:Window" --pretty # dump a UI subtree
|
|
234
|
+
platynui-cli highlight "//control:Button[@Name='OK']" # visually confirm on screen
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
`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`.
|
|
238
|
+
|
|
239
|
+
## Troubleshooting
|
|
240
|
+
|
|
241
|
+
- **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`.
|
|
242
|
+
- **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).
|
|
243
|
+
- **Wayland: clicks land wrong / screenshots fail** → use an X11 (or XWayland) session; Wayland is degraded for input injection and screen coordinates.
|
|
244
|
+
- **`ElementNotFoundError`** → check the namespace prefix (`item:`/`app:`), prefer `@Id`, and verify the selector with `platynui-cli query`.
|
|
245
|
+
- **`ProviderError: requires building with feature 'mock-provider'`** → `use_mock=${True}` needs a source build; the published wheel has no mock provider.
|
|
246
|
+
|
|
247
|
+
## When to Load Additional References
|
|
248
|
+
|
|
249
|
+
| Need | Reference File |
|
|
250
|
+
|------|----------------|
|
|
251
|
+
| Installing the pre-release, verifying it, or a failed install | `references/install.md` |
|
|
252
|
+
| Full keyword signatures, args, return types | `references/keywords-reference.md` |
|
|
253
|
+
| XPath syntax, namespaces, roles, axes, locator best practices | `references/locators-and-queries.md` |
|
|
254
|
+
| `platynui-cli` subcommands + the inspector | `references/cli-and-inspector.md` |
|
|
255
|
+
| Install matrix, Linux AT-SPI/X11/Wayland, mock, Docker | `references/platform-setup.md` |
|
|
256
|
+
| BareMetal-vs-high-level status, version footgun, migration | `references/status-and-migration.md` |
|
|
257
|
+
|
|
258
|
+
## Companion Skills
|
|
259
|
+
|
|
260
|
+
| Need | Skill |
|
|
261
|
+
|------|-------|
|
|
262
|
+
| Mobile app tests with AppiumLibrary | `rf-appium` (plugin `rf-mobile`) |
|
|
263
|
+
| Install Robot Framework or a library, fix the environment | `rf-setup` (plugin `rf-core`) |
|
|
264
|
+
| Write tests, suites, user keywords, resources and variables in Robot Framework syntax | `rf-language` (plugin `rf-core`) |
|
|
265
|
+
|
|
266
|
+
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>`.
|