robotframework-plugins 2026.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. robotframework_plugins/__init__.py +14 -0
  2. robotframework_plugins/_assets/catalog.json +143 -0
  3. robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
  4. robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
  5. robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
  6. robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
  7. robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
  8. robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
  9. robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
  10. robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
  11. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +113 -0
  12. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
  13. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
  14. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
  15. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
  16. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/async-jobs.md +42 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/loose-assertions.md +20 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +120 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/loose-assertions.md +18 -0
  31. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  32. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  33. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  34. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  35. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +13 -0
  36. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  37. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +120 -0
  38. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  39. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  40. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  41. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +445 -0
  42. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +128 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  50. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  51. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +517 -0
  52. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  108. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  109. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  110. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +119 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +123 -0
  115. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  116. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  117. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +10 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +268 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  128. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  129. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  130. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  143. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  144. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  145. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  146. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  147. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  148. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  149. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +134 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/selector-drift.md +29 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  172. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  173. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  174. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  175. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  176. robotframework_plugins/_assets.py +120 -0
  177. robotframework_plugins/_catalog.py +123 -0
  178. robotframework_plugins/_snapshot.py +320 -0
  179. robotframework_plugins/adapters/__init__.py +53 -0
  180. robotframework_plugins/adapters/_base.py +400 -0
  181. robotframework_plugins/adapters/claude_code.py +312 -0
  182. robotframework_plugins/adapters/claude_desktop.py +129 -0
  183. robotframework_plugins/adapters/codex.py +276 -0
  184. robotframework_plugins/adapters/copilot.py +87 -0
  185. robotframework_plugins/adapters/cursor.py +295 -0
  186. robotframework_plugins/adapters/goose.py +240 -0
  187. robotframework_plugins/adapters/opencode.py +170 -0
  188. robotframework_plugins/bundle.py +85 -0
  189. robotframework_plugins/cli.py +1311 -0
  190. robotframework_plugins/detect.py +121 -0
  191. robotframework_plugins/manifest.py +338 -0
  192. robotframework_plugins/py.typed +0 -0
  193. robotframework_plugins/skillzip.py +39 -0
  194. robotframework_plugins/transforms.py +725 -0
  195. robotframework_plugins-2026.11.0.dist-info/METADATA +198 -0
  196. robotframework_plugins-2026.11.0.dist-info/RECORD +199 -0
  197. robotframework_plugins-2026.11.0.dist-info/WHEEL +4 -0
  198. robotframework_plugins-2026.11.0.dist-info/entry_points.txt +2 -0
  199. robotframework_plugins-2026.11.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,139 @@
1
+ # Arguments
2
+
3
+ - [Argument forms](#argument-forms)
4
+ - [Typed arguments (RF 7.3+)](#typed-arguments-rf-73)
5
+ - [Named arguments at the call site](#named-arguments-at-the-call-site)
6
+ - [Wrappers](#wrappers)
7
+ - [Returning values](#returning-values)
8
+
9
+ Code blocks are complete files; keywords are defined in the same block or in `assets/examples/resources/`.
10
+
11
+ ## Argument forms
12
+
13
+ | Form | Syntax | Notes |
14
+ |---|---|---|
15
+ | Positional | `${product}` | Required, in order |
16
+ | Default | `${quantity}=1` | No spaces around `=`; an empty default is `${note}=${EMPTY}` (robocop ARG03) |
17
+ | Default from an earlier argument | `${to}=${from}` | Only earlier arguments are visible |
18
+ | Varargs | `@{items}` | Collects the remaining positional values |
19
+ | Named-only | After `@{items}`, or after a bare `@{}` | Must be passed as `name=value`; defaults in any order |
20
+ | Free named | `&{options}` | Collects the remaining `name=value` pairs; always last |
21
+
22
+ Order in `[Arguments]`: positional, defaults, `@{varargs}` (or `@{}`), named-only, `&{kwargs}`.
23
+
24
+ ```robotframework
25
+ *** Test Cases ***
26
+ Argument Forms
27
+ ${r}= Describe apple
28
+ Should Be Equal ${r} apple x1 []
29
+ ${r}= Describe apple 3 red ripe unit=kg
30
+ Should Be Equal ${r} apple x3 ['red', 'ripe']
31
+ ${r}= Range Text 5
32
+ Should Be Equal ${r} 5-5
33
+ ${r}= Wait Time timeout=5s
34
+ Should Be Equal ${r} 5s
35
+
36
+ *** Keywords ***
37
+ Describe
38
+ [Arguments] ${product} ${quantity}=1 @{notes} ${unit}=pcs &{extra}
39
+ RETURN ${product} x${quantity} ${notes}
40
+
41
+ Range Text
42
+ [Arguments] ${from} ${to}=${from}
43
+ RETURN ${from}-${to}
44
+
45
+ Wait Time
46
+ [Arguments] @{} ${timeout}=10s
47
+ RETURN ${timeout}
48
+ ```
49
+
50
+ Choosing:
51
+ - Two or three positional arguments at most; more values usually belong in named-only arguments with defaults.
52
+ - A boolean switch reads best as a named-only argument: `Login demo mode remember=${True}`.
53
+ - Values inside the keyword name are embedded arguments (see the embedded-arguments reference); they cannot have defaults or varargs.
54
+
55
+ ## Typed arguments (RF 7.3+)
56
+
57
+ `${name: type}` converts the value before the keyword runs and fails the call with a clear message when conversion fails. The same syntax types `VAR`, the Variables section and `FOR` variables.
58
+
59
+ ```robotframework
60
+ *** Test Cases ***
61
+ Typed Arguments
62
+ ${total}= Order Total 3 2.5
63
+ Should Be Equal ${total} ${7.5}
64
+ Set Mode FAST
65
+ Sum All 1 2 3
66
+
67
+ *** Keywords ***
68
+ Order Total
69
+ [Arguments] ${quantity: int} ${price: float} ${gift: bool}=False
70
+ RETURN ${{ $quantity * $price }}
71
+
72
+ Set Mode
73
+ [Arguments] ${mode: Literal["fast", "safe"]}
74
+ Should Be Equal ${mode} fast
75
+
76
+ Sum All
77
+ [Arguments] @{numbers: int}
78
+ ${sum}= Evaluate sum($numbers)
79
+ Should Be Equal ${sum} ${6}
80
+ ```
81
+
82
+ - `${count}: int` (type after the closing brace) is invalid on every version: "Invalid argument syntax '${count}: int'".
83
+ - On RF 7.0–7.2, `${count: int}` passes `robot --dryrun` and fails at run time with a "Variable '${count}' not found" error, because the argument is named `${count: int}`. Keep `${count}` and convert: `${count}= Convert To Integer ${count}`.
84
+ - `Literal[...]` accepts only the listed values; string matching is case-insensitive and normalizes to the listed form (`FAST` becomes `fast`).
85
+ - `&{options: int}` converts every value; `@{numbers: int}` every item.
86
+ - Unions stop at `str`: `${v: int | str}` keeps `"10"` a string, because `str` accepts it first. Put `str` last and expect the first type that accepts the value; the dry run does not show this.
87
+ - Typed defaults are converted too: `${gift: bool}=False` gives `${False}`.
88
+
89
+ ## Named arguments at the call site
90
+
91
+ - `name=value` is recognised only when `name` matches an argument of the called keyword; otherwise the whole text is a positional value.
92
+ - A space before `=` makes the cell positional without any error: `timeout =5s` passes the text `timeout =5s`. The dry run does not catch it.
93
+ - Named-argument syntax cannot come from a variable: `${pair}` containing `timeout=5s` is passed as one positional value.
94
+ - To pass a literal `name=value` text positionally, escape the equals sign: `timeout\=5s`.
95
+
96
+ ```robotframework
97
+ *** Test Cases ***
98
+ Named Versus Positional
99
+ ${r}= Show timeout=5s
100
+ Should Be Equal ${r} first:default timeout:5s
101
+ ${r}= Show timeout\=5s
102
+ Should Be Equal ${r} first:timeout=5s timeout:10s
103
+ VAR ${pair} timeout=5s
104
+ ${r}= Show ${pair}
105
+ Should Be Equal ${r} first:timeout=5s timeout:10s
106
+
107
+ *** Keywords ***
108
+ Show
109
+ [Arguments] ${first}=default ${timeout}=10s
110
+ RETURN first:${first} timeout:${timeout}
111
+ ```
112
+
113
+ ## Wrappers
114
+
115
+ A keyword that adds behaviour around another keyword forwards every argument unchanged with `@{args}` and `&{kwargs}`; named arguments then reach the inner keyword as named arguments.
116
+
117
+ ```robotframework
118
+ *** Test Cases ***
119
+ Wrapper Forwards Everything
120
+ ${r}= Logged Show timeout=1s
121
+ Should Be Equal ${r} first:default timeout:1s
122
+
123
+ *** Keywords ***
124
+ Logged Show
125
+ [Arguments] @{args} &{kwargs}
126
+ Log calling Show with ${args} ${kwargs}
127
+ ${r}= Show @{args} &{kwargs}
128
+ RETURN ${r}
129
+
130
+ Show
131
+ [Arguments] ${first}=default ${timeout}=10s
132
+ RETURN first:${first} timeout:${timeout}
133
+ ```
134
+
135
+ ## Returning values
136
+
137
+ - `RETURN ${value}` (RF 5.0+) returns and leaves the keyword; `RETURN ${a} ${b}` returns a list.
138
+ - `[Return]` is legacy (robocop DEPR11); `Return From Keyword` and `Return From Keyword If` are legacy (DEPR10). Use `RETURN`, or `IF $done RETURN ${value}`.
139
+ - Assign with the project's style: `${total}= Keyword` (the most common), `${total} = Keyword`, or `${total} Keyword`.
@@ -0,0 +1,175 @@
1
+ # Control Structures
2
+
3
+ - [Where control structures belong](#where-control-structures-belong)
4
+ - [IF and inline IF](#if-and-inline-if)
5
+ - [FOR loops](#for-loops)
6
+ - [WHILE loops](#while-loops)
7
+ - [BREAK, CONTINUE and RETURN](#break-continue-and-return)
8
+ - [TRY and EXCEPT](#try-and-except)
9
+ - [GROUP](#group)
10
+ - [Nesting, retries and timeouts](#nesting-retries-and-timeouts)
11
+
12
+ Markers (`IF`, `ELSE IF`, `ELSE`, `FOR`, `WHILE`, `TRY`, `EXCEPT`, `FINALLY`, `GROUP`, `END`) are upper case and case-sensitive. Code blocks are complete files.
13
+
14
+ ## Where control structures belong
15
+
16
+ Keep `FOR`, `WHILE`, `IF` and `TRY` out of test case bodies: a test case reads as a sequence of steps, and the logic goes into a user keyword whose name says what it does. The one exception is a templated test, where `FOR` or `IF` feeds data rows to the template (see the templates reference).
17
+
18
+ ## IF and inline IF
19
+
20
+ ```robotframework
21
+ *** Test Cases ***
22
+ Conditions
23
+ Classify ${5}
24
+ Classify ${50}
25
+
26
+ *** Keywords ***
27
+ Classify
28
+ [Arguments] ${n}
29
+ IF $n > 10
30
+ Log big
31
+ ELSE IF $n > 3
32
+ Log medium
33
+ ELSE
34
+ Log small
35
+ END
36
+ IF $n == 50 Log fifty
37
+ ${size}= IF $n > 10 Set Variable big ELSE Set Variable small
38
+ Should Not Be Equal ${size} ${None}
39
+ ```
40
+
41
+ - An inline IF with no matching branch assigns `None`: `${v}= IF $n > 10 Set Variable big` leaves `${v}` as `None` when `$n` is 5. Add an `ELSE` branch.
42
+ - Keep an inline IF on one line (robocop MISC11); use a block when it gets long.
43
+ - `Run Keyword If`/`Run Keyword Unless` are legacy (robocop DEPR08).
44
+ - Conditions are Python expressions; use `$var` (see the variables reference).
45
+
46
+ ## FOR loops
47
+
48
+ ```robotframework
49
+ *** Test Cases ***
50
+ Loops
51
+ Loop Variants
52
+
53
+ *** Keywords ***
54
+ Loop Variants
55
+ VAR @{names} alice bob
56
+ VAR @{ages} 30 40
57
+ VAR &{roles} alice=admin bob=user
58
+ FOR ${name} IN @{names}
59
+ Log ${name}
60
+ END
61
+ FOR ${i} IN RANGE 1 4
62
+ Log ${i}
63
+ END
64
+ FOR ${index} ${name} IN ENUMERATE @{names} start=1
65
+ Log ${index}: ${name}
66
+ END
67
+ FOR ${name} ${age} IN ZIP ${names} ${ages} mode=STRICT
68
+ Log ${name} is ${age}
69
+ END
70
+ FOR ${name} ${role} IN &{roles}
71
+ Log ${name} has ${role}
72
+ END
73
+ ```
74
+
75
+ - `IN ZIP` takes lists as `${lists}`, not `@{lists}`. Set `mode=STRICT`, `SHORTEST` or `LONGEST` (with `fill=`) explicitly; the default may change.
76
+ - Iterating a dictionary with `IN &{dict}` yields key and value pairs.
77
+ - Loop variables are typed on RF 7.3+: `FOR ${i: int} IN 1 2`.
78
+
79
+ ## WHILE loops
80
+
81
+ ```robotframework
82
+ *** Test Cases ***
83
+ While Loop
84
+ Count Down
85
+
86
+ *** Keywords ***
87
+ Count Down
88
+ VAR ${n} ${3}
89
+ WHILE $n > 0 limit=10
90
+ ${n}= Evaluate $n - 1
91
+ END
92
+ WHILE True limit=3 on_limit=pass
93
+ Log polling
94
+ END
95
+ ```
96
+
97
+ - The default limit is 10 000 iterations; set `limit=` to a count (`10`, `10x`) or a time (`30s`), or `NONE`.
98
+ - `on_limit=pass` (RF 6.1+) ends the loop without failing; `on_limit_message=` customises the failure.
99
+
100
+ ## BREAK, CONTINUE and RETURN
101
+
102
+ - `BREAK` and `CONTINUE` work only directly inside a `FOR` or `WHILE` body. In a keyword called from the loop they fail with "BREAK is not allowed in this context" (robocop MISC08). Return a value and test it in the loop instead.
103
+ - `RETURN` inside a loop leaves the whole keyword. In a test case body `RETURN` is an error (robocop ERR14).
104
+ - `Exit For Loop`, `Continue For Loop` and their `If` variants are legacy (robocop DEPR09).
105
+
106
+ ```robotframework
107
+ *** Test Cases ***
108
+ First Even
109
+ ${found}= Find First Even 3 5 8 9
110
+ Should Be Equal ${found} 8
111
+
112
+ *** Keywords ***
113
+ Find First Even
114
+ [Arguments] @{numbers}
115
+ FOR ${n} IN @{numbers}
116
+ IF int($n) % 2 CONTINUE
117
+ RETURN ${n}
118
+ END
119
+ Fail no even number
120
+ ```
121
+
122
+ ## TRY and EXCEPT
123
+
124
+ ```robotframework
125
+ *** Test Cases ***
126
+ Handling Errors
127
+ Handle Errors
128
+
129
+ *** Keywords ***
130
+ Handle Errors
131
+ TRY
132
+ Fail Connection refused: port 8080
133
+ EXCEPT Connection refused* type=GLOB AS ${error}
134
+ Log retrying after: ${error}
135
+ EXCEPT Timeout Invalid* type=GLOB
136
+ Log other known error
137
+ ELSE
138
+ Log no error
139
+ FINALLY
140
+ Log cleanup
141
+ END
142
+ ```
143
+
144
+ - Messages match exactly by default; `type=GLOB`, `type=REGEXP` or `type=START` change that. Backslashes in a `REGEXP` pattern are doubled.
145
+ - `AS ${error}` stores the message.
146
+ - Syntax errors and fatal errors cannot be caught.
147
+ - `TRY` replaces `Run Keyword And Ignore Error`, `Run Keyword And Return Status` and `Run Keyword And Expect Error` when they only control flow.
148
+ - Do not wrap templated rows in `TRY`; templated tests already continue on failure.
149
+
150
+ ## GROUP
151
+
152
+ `GROUP` (RF 7.2+) labels a block in the log and shares the surrounding variable scope. Prefer a user keyword when the block is reused or has a name worth calling.
153
+
154
+ ```robotframework
155
+ # RF 7.2+
156
+ *** Test Cases ***
157
+ Grouped Steps
158
+ Prepare And Check
159
+
160
+ *** Keywords ***
161
+ Prepare And Check
162
+ GROUP Prepare data
163
+ VAR ${value} 42
164
+ END
165
+ GROUP Check data
166
+ Should Be Equal ${value} 42
167
+ END
168
+ ```
169
+
170
+ ## Nesting, retries and timeouts
171
+
172
+ - Keep nesting to at most four levels. Deeper logic, parsing and computation belong in a Python keyword library.
173
+ - For a flaky step, first use the library's own waiting or retrying assertion (for example Browser's assertion operators with a timeout, SeleniumLibrary's `Wait Until …` keywords). Use `Wait Until Keyword Succeeds 3x 1s Keyword` only around keywords that do not wait themselves; retrying a waiting keyword multiplies the timeouts.
174
+ - `WHILE … limit=` is an alternative when the retry needs custom logic.
175
+ - A keyword `[Timeout]` has no default. A test timeout does not interrupt the test teardown; a keyword timeout inside the teardown does.
@@ -0,0 +1,135 @@
1
+ # Embedded Arguments
2
+
3
+ - [Matching rules](#matching-rules)
4
+ - [The shortest-match trap](#the-shortest-match-trap)
5
+ - [Custom patterns](#custom-patterns)
6
+ - [Mixing embedded and normal arguments](#mixing-embedded-and-normal-arguments)
7
+ - [Conflicts between keywords](#conflicts-between-keywords)
8
+ - [BDD step definitions](#bdd-step-definitions)
9
+
10
+ A keyword name can contain arguments: `Select Team "${city}" "${team}"` is called as `Select Team "Los Angeles" "Lakers"`. Code blocks are complete files; `assets/examples/resources/embedded.resource` holds the reference versions.
11
+
12
+ ## Matching rules
13
+
14
+ - Matching ignores case: `select fruit apple` calls `Select Fruit ${name}`.
15
+ - Spaces and underscores are significant: `Select_fruit apple` does not match `Select Fruit ${name}`.
16
+ - Embedded arguments cannot have defaults and cannot be varargs.
17
+ - By default an embedded argument matches any text (`.*?`), including other words of the call.
18
+ - A value passed as a variable (`Select Fruit ${fruit}`) is not checked against the pattern.
19
+ - Keep literal words between arguments; `${year}-${month}` needs patterns to be unambiguous.
20
+
21
+ ## The shortest-match trap
22
+
23
+ With default patterns, adjacent embedded arguments split the call at the first possible place. A dry run passes, because some keyword matched; only a real run shows the wrong values.
24
+
25
+ ```robotframework
26
+ # Wrong: `city` receives "Los" and `team` receives "Angeles Lakers".
27
+ *** Keywords ***
28
+ Select Team ${city} ${team}
29
+ Log city=${city} team=${team}
30
+ ```
31
+
32
+ Two fixes, both in `embedded.resource` and exercised by `tests/05__embedded.robot`:
33
+
34
+ ```robotframework
35
+ *** Test Cases ***
36
+ Multi-Word Cities Bind Correctly
37
+ Select Team "Los Angeles" "Lakers"
38
+ Should Be Equal ${CITY} Los Angeles
39
+ Pick Team Golden State Warriors
40
+ Should Be Equal ${CITY} Golden State
41
+
42
+ *** Keywords ***
43
+ Select Team "${city}" "${team}"
44
+ [Documentation] Quotes delimit each value.
45
+ VAR ${CITY} ${city} scope=TEST
46
+
47
+ Pick Team ${city} ${team:\S+}
48
+ [Documentation] The team is one word, so the city takes the rest.
49
+ VAR ${CITY} ${city} scope=TEST
50
+ ```
51
+
52
+ - Quoting is the clearest fix when you control the call sites.
53
+ - A pattern on the last argument fixes existing unquoted calls such as `Select Team Los Angeles Lakers`, as long as the team name is one word.
54
+ - On RF 7.3+ the fix combines with a type: `${count: int:\d+}`.
55
+ - After writing embedded keywords, run at least one test that uses them and check the logged values.
56
+
57
+ ## Custom patterns
58
+
59
+ `${name:regex}` restricts what an argument matches. The regex is Python syntax inside Robot Framework data, so backslashes are written once (`\d`, `\S`).
60
+
61
+ ```robotframework
62
+ *** Test Cases ***
63
+ Patterns
64
+ Wait 5 Seconds
65
+ Choose Animal CAT
66
+ Book For 2026-10-01
67
+
68
+ *** Keywords ***
69
+ Wait ${count:\d+} Seconds
70
+ Should Be True ${count} == 5
71
+
72
+ Choose Animal ${animal:(?i)cat|dog}
73
+ Should Be Equal ${animal} CAT
74
+
75
+ Book For ${date:\d{4}-\d{2}-\d{2}}
76
+ Should Match Regexp ${date} ^2026-
77
+ ```
78
+
79
+ - Lone braces in a pattern are escaped (`\{`, `\}`); counted braces such as `\d{4}` work as written.
80
+ - `(?i)` makes one pattern case-insensitive (RF 7.2+).
81
+ - Alternatives need no group: `${animal:cat|dog}` matches either word.
82
+ - A pattern that should match a leading space needs `\ ` or `\s`.
83
+ - Types with patterns (RF 7.3+): `${count: int:\d+}` or `${when: date:\d{4}-\d{2}-\d{2}}`.
84
+
85
+ ## Mixing embedded and normal arguments
86
+
87
+ From RF 6.1 a user keyword may have embedded arguments and an `[Arguments]` list:
88
+
89
+ ```robotframework
90
+ *** Test Cases ***
91
+ Mixed
92
+ Order 3 Apples express=${True}
93
+
94
+ *** Keywords ***
95
+ Order ${count:\d+} Apples
96
+ [Arguments] ${express}=${False}
97
+ Should Be True ${count} == 3 and ${express}
98
+ ```
99
+
100
+ ## Conflicts between keywords
101
+
102
+ When several keywords match one call:
103
+ - a keyword in the same file wins over imported ones;
104
+ - a normal keyword wins over an embedded-argument keyword with the same text;
105
+ - among embedded keywords, one wins when the other also matches its name but not the other way round: `Select ${x} Team` beats `Select ${x}` for `Select Lakers Team` (RF 6.0+); a stricter pattern alone (`${n:\d+}` versus `${n}`) does not make a keyword win;
106
+ - if no keyword wins, the call fails with "Multiple keywords with name '…' found".
107
+
108
+ Pairs such as `${type} Framework` and `Robot ${action}` both match `Robot Framework` and cannot be resolved automatically: rename one or narrow a pattern. For the same name defined in two resource files, see the resources reference (qualified calls, robocop KW06).
109
+
110
+ ## BDD step definitions
111
+
112
+ Steps are called with `Given`, `When`, `Then`, `And` or `But`; Robot Framework removes the prefix and looks up the rest. Define step keywords without the prefix:
113
+
114
+ ```robotframework
115
+ *** Test Cases ***
116
+ Checkout Scenario
117
+ Given The Cart Contains 2 "Blue Mug"
118
+ When The User Checks Out
119
+ Then The Order Total Is 2 Items
120
+
121
+ *** Keywords ***
122
+ The Cart Contains ${count:\d+} "${product}"
123
+ VAR ${ITEMS} ${count} scope=TEST
124
+
125
+ The User Checks Out
126
+ Log checking out ${ITEMS} items
127
+
128
+ The Order Total Is ${count:\d+} Items
129
+ Should Be Equal As Integers ${ITEMS} ${count}
130
+ ```
131
+
132
+ - A keyword defined as `Given The App Is Open` is found only through that exact prefix; `When The App Is Open` fails with "No keyword with name".
133
+ - From RF 7.1 a prefix is also stripped when the keyword starts with an embedded argument (`Given ${user} Logs In`).
134
+ - Keep one step keyword per sentence; share implementation through normal keywords that the steps call.
135
+ - Quote or pattern-restrict every embedded value in a step, because steps often place values next to each other.
@@ -0,0 +1,90 @@
1
+ # Migration From Legacy Syntax
2
+
3
+ - [Legacy to modern table](#legacy-to-modern-table)
4
+ - [Finding legacy syntax](#finding-legacy-syntax)
5
+ - [Rewriting safely](#rewriting-safely)
6
+
7
+ Rule IDs verified with Robocop 9.1.0 (2026-09-27). Check the project's Robot Framework version (version gate) before rewriting: a replacement needs at least the listed version.
8
+
9
+ ## Legacy to modern table
10
+
11
+ | Legacy construct | Modern replacement | Min RF | Robocop rule |
12
+ |---|---|---|---|
13
+ | `[Return] ${x}` | `RETURN ${x}` | 5.0 | DEPR11 |
14
+ | `Return From Keyword` / `Return From Keyword If` | `RETURN` / `IF $cond RETURN ${x}` | 5.0 | DEPR10 |
15
+ | `Run Keyword If` / `Run Keyword Unless` | `IF` block or inline `IF` | 4.0 | DEPR08 |
16
+ | `Exit For Loop` / `Continue For Loop` (and their `If` variants) | `BREAK` / `CONTINUE` (inside `IF`) | 5.0 | DEPR09 |
17
+ | `Set Variable` / `Set Test Variable` / `Set Suite Variable` / `Set Global Variable` / `Set Local Variable` | `VAR` with `scope=TEST`, `SUITE`, `GLOBAL` | 7.0 | DEPR05 |
18
+ | `Create List` / `Create Dictionary` | `VAR @{list} …` / `VAR &{dict} …` | 7.0 | DEPR06 |
19
+ | `Catenate` | `VAR ${s} a b separator=-` | 7.0 | none |
20
+ | `Set Variable If` | inline `IF`/`ELSE` with `VAR` or `Set Variable` | 7.0 | none |
21
+ | `Force Tags` / `Default Tags` | `Test Tags`, plus `[Tags] -tag` to remove one (7.0) | 6.0 | DEPR07 (`Force Tags`) |
22
+ | `WITH NAME` | `AS` | 6.0 | DEPR03 |
23
+ | Singular section headers (`*** Setting ***`, `*** Test Case ***`) | Plural headers (`*** Settings ***`, `*** Test Cases ***`) | 6.0 | DEPR04 |
24
+ | `Run Keyword And Ignore Error` / `Run Keyword And Return Status` used for flow control | `TRY`/`EXCEPT` | 5.0 | none |
25
+ | Argument types only described in `[Documentation]` | Typed arguments `${count: int}` | 7.3 | ANN02 (disabled by default) |
26
+ | `Set Test Variable` (or another `Set … Variable`) with a typed name | `VAR ${count: int} 5` | 7.3 | ANN04 |
27
+
28
+ - DEPR05, DEPR06 and DEPR11 are info-level; the others are warnings, ANN04 is an error.
29
+ - `Catenate`, `Set Variable If` and `Default Tags` are not reported by Robocop 9.1; search for them yourself.
30
+ - `Default Tags` has no direct replacement: give the tests that need the tag `[Tags]`, or set `Test Tags` and remove the tag with `[Tags] -tag` where it does not apply.
31
+
32
+ Before and after, for a keyword that uses most of them:
33
+
34
+ ```robotframework
35
+ # Legacy: do not copy.
36
+ *** Setting ***
37
+ Library Collections WITH NAME Coll
38
+
39
+ *** Keyword ***
40
+ Summarize
41
+ [Arguments] @{items}
42
+ ${count}= Get Length ${items}
43
+ Run Keyword If ${count} == 0 Fail empty
44
+ ${text}= Catenate SEPARATOR=, @{items}
45
+ Set Suite Variable ${LAST} ${text}
46
+ [Return] ${text}
47
+ ```
48
+
49
+ ```robotframework
50
+ *** Settings ***
51
+ Library Collections AS Coll
52
+
53
+ *** Test Cases ***
54
+ Summarize Items
55
+ ${text}= Summarize a b
56
+ Should Be Equal ${text} a,b
57
+
58
+ *** Keywords ***
59
+ Summarize
60
+ [Arguments] @{items}
61
+ ${count}= Get Length ${items}
62
+ IF $count == 0 Fail empty
63
+ VAR ${text} @{items} separator=,
64
+ VAR ${LAST} ${text} scope=SUITE
65
+ RETURN ${text}
66
+ ```
67
+
68
+ ## Finding legacy syntax
69
+
70
+ Run Robocop with the deprecation group, repeating `-s` for each selection (a comma-separated list such as `DEPR08,DEPR11` is rejected as "No rule selected"), and pass `--target-version` with the project's Robot Framework major version so that only rules applicable to that version run:
71
+
72
+ ```bash
73
+ uv run robocop check --no-cache --target-version 7 -s "DEPR*" tests resources
74
+ uv run robocop check --no-cache --target-version 7 -s DEPR08 -s DEPR11 resources/cart.resource
75
+ uv run robocop check --no-cache -s ANN04 -s KW06 tests resources
76
+ ```
77
+
78
+ - With `--target-version 6`, the `VAR` rules DEPR05/DEPR06 are not reported, because `VAR` needs RF 7.0.
79
+ - `rf_conventions` lists the constructs it found in `legacy` with the same rule IDs, and its `migrate-legacy` advice prints the matching `-s` options.
80
+ - Robocop is optional. Without it, search: `grep -rnE 'Run Keyword (If|Unless)|\[Return\]|Force Tags|Set (Test|Suite|Global) Variable|WITH NAME' tests resources`.
81
+ - Robocop also reports documentation rules (DOC01–DOC03) by default. Fix them only when the project's Robocop configuration asks for them; they are not part of a syntax migration.
82
+
83
+ ## Rewriting safely
84
+
85
+ 1. Establish the Robot Framework version; do not introduce a replacement newer than it (`VAR` needs 7.0, typed arguments 7.3).
86
+ 2. Rewrite one file or one keyword family at a time.
87
+ 3. Replace `Set Suite Variable` only when the scope stays the same: `scope=SUITE` is not visible in child suites (use `SUITES` on RF 7.1+ or `GLOBAL`).
88
+ 4. `Run Keyword If` with `ELSE IF`/`ELSE` arguments becomes an `IF`/`ELSE IF`/`ELSE` block; a single call becomes an inline `IF`.
89
+ 5. `Run Keyword And Return Status` that only feeds an `IF` becomes `TRY`/`EXCEPT`; keep it when the status is really the result.
90
+ 6. Dry run, run Robocop again (no DEPR findings left), then run the affected tests for real.
@@ -0,0 +1,127 @@
1
+ # Resources and Variable Files
2
+
3
+ - [Default layout](#default-layout)
4
+ - [Resource files](#resource-files)
5
+ - [Imports and paths](#imports-and-paths)
6
+ - [Variable files per environment](#variable-files-per-environment)
7
+ - [Keyword name conflicts](#keyword-name-conflicts)
8
+ - [Private keywords and library aliases](#private-keywords-and-library-aliases)
9
+
10
+ ## Default layout
11
+
12
+ Follow the layout `rf_conventions` reports (`layout.resource_dir`, `layout.variable_files`). When the project has none yet:
13
+
14
+ ```text
15
+ resources/
16
+ common.resource # Library imports and settings shared by all resources
17
+ login.resource # one <domain>.resource per domain; imports common.resource
18
+ cart.resource
19
+ variables/
20
+ dev.yaml # one variable file per environment
21
+ staging.yaml
22
+ libraries/ # project Python keyword libraries (on the python-path)
23
+ tests/
24
+ ```
25
+
26
+ - `resource_dir` is the directory with the most `.resource` files, else the first of `resources/`, `keywords/`, `res/` that exists, else create `resources/`.
27
+ - Each suite imports the domain resources it needs; the domain resources import `common.resource`.
28
+ - Never overwrite an existing resource or variable file unless asked; add keywords to the matching domain file or create a new one.
29
+
30
+ ## Resource files
31
+
32
+ - Extension `.resource`. Settings may contain only imports (`Library`, `Resource`, `Variables`), `Documentation` and `Keyword Tags`; anything else ("Setting 'Test Setup' is not allowed in resource file") is ignored with an error.
33
+ - No `*** Test Cases ***` section: a resource with tests fails to import.
34
+ - `*** Variables ***` and `*** Keywords ***` are allowed.
35
+
36
+ ```robotframework
37
+ *** Settings ***
38
+ Documentation Cart keywords. Imports what the keywords need, nothing else.
39
+ Library Collections
40
+ Keyword Tags cart
41
+
42
+ *** Variables ***
43
+ ${MAX_ITEMS} 10
44
+
45
+ *** Keywords ***
46
+ Cart Should Not Be Full
47
+ [Documentation] Fails when ``cart`` holds ``${MAX_ITEMS}`` items or more.
48
+ [Arguments] ${cart}
49
+ ${size}= Get Length ${cart}
50
+ Should Be True ${size} < ${MAX_ITEMS}
51
+ ```
52
+
53
+ ## Imports and paths
54
+
55
+ - A relative path in `Resource`, `Variables` or `Library` resolves against the directory of the importing file first, then against the python-path (`--pythonpath`, `python-path` in `robot.toml`).
56
+ - Use paths relative to the importing file (`../resources/cart.resource`) or `${CURDIR}/…`; avoid paths that depend on the current working directory.
57
+ - Use `/` as the separator on every OS.
58
+ - An import that fails is reported as an error and the suite still runs, so dry-run after changing imports.
59
+
60
+ ## Variable files per environment
61
+
62
+ | Kind | Needs | Notes |
63
+ |---|---|---|
64
+ | YAML (`.yaml`/`.yml`) | PyYAML in the project environment: `uv add pyyaml` (not using uv: add `pyyaml` with the project's tool, see rf-setup) | Top level is a mapping; takes no arguments (robocop ERR04) |
65
+ | JSON (`.json`) | Nothing extra (RF 6.1+) | Top level is an object |
66
+ | Python (`.py`) | Nothing extra | Module attributes, or `get_variables(env)` that returns a dict; takes arguments |
67
+ | Resource (`.resource`) | Nothing extra | `*** Variables ***` section, imported with `Resource` |
68
+
69
+ Select the environment on the command line; plain `robot` does not read `robot.toml`:
70
+
71
+ ```bash
72
+ uv run robot --variablefile variables/staging.yaml tests
73
+ uv run robot --variablefile variables/common.py --variablefile variables/dev.yaml tests
74
+ ```
75
+
76
+ With robotcode, a `robot.toml` profile can hold the list: `[profiles.staging]` with `variable-files = ["variables/staging.yaml"]`, run as `robotcode -p staging robot`.
77
+
78
+ - The suite keeps dev defaults in its own `*** Variables ***` section; `--variablefile` overrides them.
79
+ - Python variable files: names starting with `_` are skipped; `__all__` limits what is exported; `LIST__name` and `DICT__name` create `@{name}` and `&{name}`; `get_variables(env="dev")` receives arguments given as `common.py:staging`.
80
+ - A missing PyYAML fails with "Using YAML variable files requires PyYAML module to be installed".
81
+
82
+ ## Keyword name conflicts
83
+
84
+ The same keyword name in two imported resource files fails at the call with "Multiple keywords with name 'Open App' found". Resolve it by:
85
+ - calling the keyword by its full name, `<resource file name>.<Keyword>` (`admin.Open App`), or `<Library>.<Keyword>` for library keywords;
86
+ - `Set Library Search Order admin` in a setup, which also works for resource file names;
87
+ - renaming one keyword, which is usually the best fix.
88
+
89
+ ```robotframework
90
+ *** Settings ***
91
+ Resource ../resources/calc.resource
92
+
93
+ *** Test Cases ***
94
+ Qualified Calls
95
+ calc.The Calculator Is Cleared
96
+ BuiltIn.Log fully qualified library keyword
97
+ ```
98
+
99
+ - The qualified form breaks when two resources share a file name in different directories; rename one of them.
100
+ - A keyword defined in the suite file itself wins over imported ones, which can hide a conflict until another suite imports both resources.
101
+ - Robocop KW06 (`ambiguous-keyword-name`, robocop 9.x, disabled by default) finds such conflicts statically: `uv run robocop check --no-cache -s KW06 tests resources`.
102
+
103
+ ## Private keywords and library aliases
104
+
105
+ - Tag helper keywords `robot:private` (RF 6.0+) so they are meant only for the file that defines them; a call from another file logs a warning ("is private and should only be called by keywords in the same file"). `Keyword Tags robot:private` is too broad; tag individual keywords.
106
+ - Import a library twice with different arguments, or give it a short name, with `AS`: `Library Collections AS Coll`, then call `Coll.Append To List`. `WITH NAME` is legacy (robocop DEPR03).
107
+
108
+ ```robotframework
109
+ *** Settings ***
110
+ Library Collections AS Coll
111
+
112
+ *** Test Cases ***
113
+ Alias And Private Helper
114
+ VAR @{items} a
115
+ Coll.Append To List ${items} b
116
+ Public Step ${items}
117
+
118
+ *** Keywords ***
119
+ Public Step
120
+ [Arguments] ${items}
121
+ Count Items ${items}
122
+
123
+ Count Items
124
+ [Tags] robot:private
125
+ [Arguments] ${items}
126
+ Length Should Be ${items} 2
127
+ ```