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.
Files changed (195) 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 +110 -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/authentication.md +58 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  31. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  32. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
  33. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  34. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
  35. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  36. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  37. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  38. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
  39. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  40. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  41. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  42. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  50. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  51. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  52. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  108. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
  109. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  110. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  115. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  116. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
  117. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  128. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  129. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  130. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  143. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  144. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  145. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  146. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  147. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
  148. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  149. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  172. robotframework_plugins/_assets.py +120 -0
  173. robotframework_plugins/_catalog.py +123 -0
  174. robotframework_plugins/_snapshot.py +230 -0
  175. robotframework_plugins/adapters/__init__.py +53 -0
  176. robotframework_plugins/adapters/_base.py +400 -0
  177. robotframework_plugins/adapters/claude_code.py +312 -0
  178. robotframework_plugins/adapters/claude_desktop.py +129 -0
  179. robotframework_plugins/adapters/codex.py +276 -0
  180. robotframework_plugins/adapters/copilot.py +87 -0
  181. robotframework_plugins/adapters/cursor.py +295 -0
  182. robotframework_plugins/adapters/goose.py +240 -0
  183. robotframework_plugins/adapters/opencode.py +170 -0
  184. robotframework_plugins/bundle.py +85 -0
  185. robotframework_plugins/cli.py +1311 -0
  186. robotframework_plugins/detect.py +121 -0
  187. robotframework_plugins/manifest.py +338 -0
  188. robotframework_plugins/py.typed +0 -0
  189. robotframework_plugins/skillzip.py +39 -0
  190. robotframework_plugins/transforms.py +725 -0
  191. robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
  192. robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
  193. robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
  194. robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
  195. robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,291 @@
1
+ # Library API variants
2
+
3
+ How Robot Framework turns a Python module or class into keywords, and the
4
+ alternatives to the default static class library. Examples need RF 7.0+
5
+ unless a block says otherwise.
6
+
7
+ - [Module or class library](#module-or-class-library)
8
+ - [Which class RF picks](#which-class-rf-picks)
9
+ - [Library scope](#library-scope)
10
+ - [Init arguments and AS](#init-arguments-and-as)
11
+ - [Embedded-argument keywords](#embedded-argument-keywords)
12
+ - [Async keywords](#async-keywords)
13
+ - [Hybrid API](#hybrid-api)
14
+ - [Dynamic API](#dynamic-api)
15
+ - [PythonLibCore](#pythonlibcore)
16
+ - [Remote libraries](#remote-libraries)
17
+
18
+ ## Module or class library
19
+
20
+ A module library exposes its public functions. Everything public counts,
21
+ including functions it imports, so `from os.path import join` adds a `Join`
22
+ keyword (checker: `leaked_keyword`). Keep module libraries small and turn
23
+ automatic discovery off:
24
+
25
+ ```python
26
+ # file: textutils.py
27
+ """Module library: only @keyword functions are keywords."""
28
+
29
+ import re
30
+
31
+ from robot.api.deco import keyword
32
+
33
+ ROBOT_AUTO_KEYWORDS = False
34
+
35
+
36
+ @keyword
37
+ def normalise_whitespace(text: str) -> str:
38
+ """Collapse runs of whitespace to one space."""
39
+ return re.sub(r"\s+", " ", text).strip()
40
+ ```
41
+
42
+ `__all__ = ["normalise_whitespace"]` also limits the keywords. A class library
43
+ (the template in SKILL.md) is the default for anything with state, init
44
+ arguments, converters or a listener. Module libraries always have `GLOBAL`
45
+ scope.
46
+
47
+ ## Which class RF picks
48
+
49
+ `Library Name` imports module `Name` and uses its class `Name` when one
50
+ exists. From RF 7.2 a module without a same-named class may contain exactly
51
+ one `@library`-decorated class, and RF uses that. `Library pkg.module.Class`
52
+ names the class explicitly on every version. Otherwise the module itself is
53
+ the library, and a class-only module reports "contains no keywords".
54
+
55
+ ## Library scope
56
+
57
+ Source: Robot Framework User Guide, "Creating test libraries" → "Library
58
+ scope". The only library scopes are `TEST` (alias `TASK`), `SUITE` and
59
+ `GLOBAL`; `SUITES` is a `VAR` scope for variables, not a library scope.
60
+
61
+ - `TEST` (default without a setting): a new instance for every test; suite
62
+ setup and teardown share another instance. Tests stay independent.
63
+ - `SUITE`: one instance per suite, shared by its tests.
64
+ - `GLOBAL`: one instance for the whole run. Module libraries are global.
65
+ - A library imported with different arguments gets a new instance for each
66
+ argument set, whatever the scope.
67
+ - A `SUITE` or `GLOBAL` library that keeps state should offer a cleanup
68
+ keyword for a suite setup or teardown; SeleniumLibrary is `GLOBAL` and
69
+ offers `Close All Browsers`.
70
+
71
+ Set the scope with `@library(scope="SUITE")` or the class attribute
72
+ `ROBOT_LIBRARY_SCOPE = "SUITE"`. `__init__` runs when an instance is created:
73
+ for every test in `TEST` scope, and also during libdoc and `--dryrun`.
74
+
75
+ ```python
76
+ # file: Counter.py
77
+ """SUITE scope: the tests of one suite share the count."""
78
+
79
+ from robot.api.deco import keyword, library
80
+
81
+
82
+ @library(scope="SUITE")
83
+ class Counter:
84
+ """Counts calls across the tests of a suite."""
85
+
86
+ def __init__(self) -> None:
87
+ self._count = 0
88
+
89
+ @keyword
90
+ def increment(self) -> int:
91
+ """Add one and return the count."""
92
+ self._count += 1
93
+ return self._count
94
+
95
+ @keyword
96
+ def reset_counter(self) -> None:
97
+ """Cleanup keyword for a suite setup or teardown."""
98
+ self._count = 0
99
+ ```
100
+
101
+ ```robotframework
102
+ # file: counter.robot
103
+ *** Settings ***
104
+ Library Counter
105
+ Suite Setup Reset Counter
106
+
107
+
108
+ *** Test Cases ***
109
+ First Test
110
+ ${count}= Increment
111
+ Should Be Equal ${count} ${1}
112
+
113
+ Second Test Sees The Same Instance
114
+ ${count}= Increment
115
+ Should Be Equal ${count} ${2}
116
+ ```
117
+
118
+ With `scope="TEST"` the second test would get `1`, and the checker would warn
119
+ with `state_in_test_scope`.
120
+
121
+ ## Init arguments and AS
122
+
123
+ `__init__` arguments are import arguments and use the same type conversion as
124
+ keywords. Named import arguments work too.
125
+
126
+ ```robotframework
127
+ *** Settings ***
128
+ Library Client https://dev.example.com timeout=10 AS DevClient
129
+ Library Client https://staging.example.com AS StagingClient
130
+ ```
131
+
132
+ Call the keywords as `DevClient.Get Status` and `StagingClient.Get Status`.
133
+ Without `AS`, the second import of the same library with different arguments
134
+ is ignored with a warning. For the checker, pass init arguments with
135
+ `--init-arg VALUE` (repeatable, one library per run).
136
+
137
+ ## Embedded-argument keywords
138
+
139
+ `@keyword("Add ${quantity} items of ${product}")` embeds arguments in the
140
+ name; put the types on the Python arguments. An inline type in the name
141
+ (`${quantity: int}`) is rejected on RF 7.3+ and the library then contains no
142
+ keywords (checker: `keyword_creation_failed`, `no_keywords`); before 7.3 the
143
+ `: int` part is read as a regular expression, so the keyword never matches.
144
+ From RF 7.0 an embedded keyword can also take normal arguments after the name.
145
+ Custom patterns use `${name:regex}` without a space after the colon.
146
+
147
+ ```python
148
+ # file: Basket.py
149
+ """Embedded arguments with Python type hints."""
150
+
151
+ from robot.api.deco import keyword, library
152
+
153
+
154
+ @library(scope="SUITE")
155
+ class Basket:
156
+ """A basket of products."""
157
+
158
+ def __init__(self) -> None:
159
+ self._items: dict[str, int] = {}
160
+
161
+ @keyword("Add ${quantity:\\d+} items of ${product}")
162
+ def add_items(self, quantity: int, product: str, note: str = "") -> int:
163
+ """Add items; ``note`` is a normal argument after the embedded ones (RF 7.0+)."""
164
+ self._items[product] = self._items.get(product, 0) + quantity
165
+ return self._items[product]
166
+ ```
167
+
168
+ ```robotframework
169
+ # file: basket.robot
170
+ *** Settings ***
171
+ Library Basket
172
+
173
+
174
+ *** Test Cases ***
175
+ Embedded And Normal Arguments
176
+ ${count}= Add 3 items of apple
177
+ Should Be Equal ${count} ${3}
178
+ ${count}= Add 2 items of apple note=gift
179
+ Should Be Equal ${count} ${5}
180
+ ```
181
+
182
+ ## Async keywords
183
+
184
+ An `async def` keyword (RF 6.1+) is awaited by Robot Framework on its own
185
+ event loop; do not start one yourself with `asyncio.run`.
186
+
187
+ ```python
188
+ # file: Waiter.py
189
+ """Async keyword."""
190
+
191
+ import asyncio
192
+
193
+ from robot.api.deco import keyword, library
194
+
195
+
196
+ @library(scope="GLOBAL")
197
+ class Waiter:
198
+ """Async waits."""
199
+
200
+ @keyword
201
+ async def wait_and_return(self, value: str, seconds: float = 0.01) -> str:
202
+ """Wait ``seconds`` and return ``value``."""
203
+ await asyncio.sleep(seconds)
204
+ return value
205
+ ```
206
+
207
+ ## Hybrid API
208
+
209
+ `get_keyword_names()` returns the keyword names; RF then looks up each name as
210
+ a method or attribute, so arguments, types and docs still come from real
211
+ callables. Use it when the set of keywords is computed at import time (for
212
+ example one keyword per configured endpoint).
213
+
214
+ ## Dynamic API
215
+
216
+ A dynamic library implements `get_keyword_names()` and
217
+ `run_keyword(name, args, kwargs)`, plus optional `get_keyword_arguments`,
218
+ `get_keyword_types`, `get_keyword_documentation`, `get_keyword_tags` and
219
+ `get_keyword_source`. Without `get_keyword_arguments` every keyword takes
220
+ `*varargs, **kwargs` (checker: `signature_lost`) and nothing is converted.
221
+ Use it for proxies to another tool or process. `get_keyword_documentation`
222
+ with `"__intro__"` / `"__init__"` returns the library and init docs.
223
+
224
+ ```python
225
+ # file: Commands.py
226
+ """Dynamic library that proxies a command table."""
227
+
228
+ from robot.api.deco import library
229
+
230
+ COMMANDS = {
231
+ "Double Value": (lambda value: value * 2, ["value"], {"value": int}, "Return ``value`` times two."),
232
+ "Join Words": (lambda *words: " ".join(words), ["*words"], {}, "Join words with spaces."),
233
+ }
234
+
235
+
236
+ @library(scope="GLOBAL")
237
+ class Commands:
238
+ """Keywords generated from the COMMANDS table."""
239
+
240
+ def get_keyword_names(self) -> list[str]:
241
+ return list(COMMANDS)
242
+
243
+ def run_keyword(self, name: str, args: list, kwargs: dict):
244
+ return COMMANDS[name][0](*args, **kwargs)
245
+
246
+ def get_keyword_arguments(self, name: str) -> list[str]:
247
+ return COMMANDS[name][1]
248
+
249
+ def get_keyword_types(self, name: str) -> dict:
250
+ return COMMANDS[name][2]
251
+
252
+ def get_keyword_documentation(self, name: str) -> str:
253
+ if name in ("__intro__", "__init__"):
254
+ return "Keywords generated from the COMMANDS table." if name == "__intro__" else ""
255
+ return COMMANDS[name][3]
256
+ ```
257
+
258
+ ```robotframework
259
+ # file: commands.robot
260
+ *** Settings ***
261
+ Library Commands
262
+
263
+
264
+ *** Test Cases ***
265
+ Dynamic Keywords Run With Converted Arguments
266
+ ${result}= Double Value 21
267
+ Should Be Equal ${result} ${42}
268
+ ${text}= Join Words a b c
269
+ Should Be Equal ${text} a b c
270
+ ```
271
+
272
+ List the keywords: `uv run python -m robot.libdoc Commands list` (with the
273
+ module on the python-path), `robotcode doc keywords libraries/Commands.py`, or the checker.
274
+ The checker skips its method-based checks (`public_method_not_keyword`,
275
+ `state_in_test_scope`) for hybrid and dynamic libraries.
276
+
277
+ ## PythonLibCore
278
+
279
+ `robotframework-pythonlibcore` (`from robotlibcore import DynamicCore,
280
+ keyword`) builds a dynamic library from several component classes; Browser
281
+ and SeleniumLibrary use it. Reach for it when a library grows beyond one
282
+ class. Add it to the project with `uv add robotframework-pythonlibcore` (see
283
+ rf-setup); it is not needed for ordinary libraries.
284
+
285
+ ## Remote libraries
286
+
287
+ The Remote library (`Library Remote http://host:8270`) calls keywords of
288
+ a library that runs in another process or machine over XML-RPC, served by a
289
+ remote server such as `robotremoteserver`. The library code itself is written
290
+ the same way; only the server wraps it. Prefer a local library unless the
291
+ code must run elsewhere.
@@ -0,0 +1,248 @@
1
+ # Failures, logging and talking to Robot Framework
2
+
3
+ How a library reports failures, writes to the log and console, handles
4
+ threads and timeouts, and reaches Robot Framework itself. Examples need RF
5
+ 7.0+ unless a block says otherwise.
6
+
7
+ - [Exceptions](#exceptions)
8
+ - [Exception names and HTML messages](#exception-names-and-html-messages)
9
+ - [Logging](#logging)
10
+ - [Threads](#threads)
11
+ - [Timeouts](#timeouts)
12
+ - [Using BuiltIn from a library](#using-builtin-from-a-library)
13
+
14
+ ## Exceptions
15
+
16
+ A keyword fails by raising. The exception class decides what happens next:
17
+
18
+ | Raise | Effect |
19
+ |---|---|
20
+ | `AssertionError` / `robot.api.Failure` | the test fails (verification failed) |
21
+ | `robot.api.ContinuableFailure` | the failure is recorded, the test continues and fails at the end |
22
+ | `robot.api.SkipExecution` | the test is marked SKIP |
23
+ | `robot.api.FatalError` | the test fails and all remaining tests fail without running |
24
+ | `ValueError` / `TypeError` / `robot.api.Error` | the keyword was used incorrectly (bad arguments, wrong state) |
25
+ | any other exception | the test fails with the exception's message |
26
+
27
+ `Failure` is an `AssertionError`, `Error` a `RuntimeError`; the `robot.api`
28
+ classes add HTML support and consistent names. `Run Keyword And Expect Error`
29
+ catches failures and errors, but not `SkipExecution` (the test is skipped),
30
+ `FatalError` or timeouts.
31
+
32
+ ```python
33
+ # file: Checks.py
34
+ """Failure classes from robot.api."""
35
+
36
+ from robot.api import ContinuableFailure, SkipExecution
37
+ from robot.api.deco import keyword, library
38
+
39
+
40
+ @library(scope="GLOBAL")
41
+ class Checks:
42
+ """Verification keywords."""
43
+
44
+ @keyword
45
+ def values_should_match(self, actual: int, expected: int) -> None:
46
+ """Fail unless the values are equal."""
47
+ if actual != expected:
48
+ raise AssertionError(f"expected {expected}, got {actual}")
49
+
50
+ @keyword
51
+ def soft_check(self, actual: int, expected: int) -> None:
52
+ """Record a mismatch and let the test continue."""
53
+ if actual != expected:
54
+ raise ContinuableFailure(f"soft check: expected {expected}, got {actual}")
55
+
56
+ @keyword
57
+ def require_feature(self, enabled: bool) -> None:
58
+ """Skip the test when the feature is disabled."""
59
+ if not enabled:
60
+ raise SkipExecution("feature disabled in this environment")
61
+ ```
62
+
63
+ ```robotframework
64
+ # file: checks.robot
65
+ *** Settings ***
66
+ Library Checks
67
+
68
+
69
+ *** Test Cases ***
70
+ Hard Failure Message
71
+ Run Keyword And Expect Error expected 2, got 1 Values Should Match 1 2
72
+
73
+ Feature Gate Skips
74
+ Require Feature no
75
+ Fail not reached
76
+ ```
77
+
78
+ ## Exception names and HTML messages
79
+
80
+ RF shows the message alone for `AssertionError`, `RuntimeError`, `Exception`
81
+ and the `robot.api` classes; other exceptions are prefixed with their class
82
+ name (`ValueError: …`). A custom exception class hides its name with
83
+ `ROBOT_SUPPRESS_NAME = True`. A message starting with `*HTML*` is rendered as
84
+ HTML in the log and report (escape any user data you put into it).
85
+
86
+ ```python
87
+ # file: Orders.py
88
+ """Custom exception without the class name in the message."""
89
+
90
+ from robot.api.deco import keyword, library
91
+
92
+
93
+ class OrderRejected(Exception):
94
+ ROBOT_SUPPRESS_NAME = True
95
+
96
+
97
+ @library(scope="GLOBAL")
98
+ class Orders:
99
+ """Order keywords."""
100
+
101
+ @keyword
102
+ def submit_order(self, quantity: int) -> int:
103
+ """Submit an order; quantities over 10 are rejected."""
104
+ if quantity > 10:
105
+ raise OrderRejected(f"order rejected: {quantity} exceeds the limit of 10")
106
+ return quantity
107
+ ```
108
+
109
+ ```robotframework
110
+ # file: orders.robot
111
+ *** Settings ***
112
+ Library Orders
113
+
114
+
115
+ *** Test Cases ***
116
+ Message Without Class Name
117
+ Run Keyword And Expect Error order rejected: 11 exceeds the limit of 10
118
+ ... Submit Order 11
119
+ ```
120
+
121
+ ## Logging
122
+
123
+ | Call | Level / target |
124
+ |---|---|
125
+ | `logger.trace(msg)`, `logger.debug(msg)` | TRACE / DEBUG (shown with `--loglevel DEBUG` or `TRACE`) |
126
+ | `logger.info(msg)` | INFO (default level of the log) |
127
+ | `logger.info(msg, html=True)` | INFO, rendered as HTML |
128
+ | `logger.info(msg, also_console=True)` | INFO plus the console |
129
+ | `logger.warn(msg)` / `logger.error(msg)` | WARN / ERROR; also listed in "Test Execution Errors" and on the console |
130
+ | `logger.console(msg)` | the console only (progress output) |
131
+
132
+ `from robot.api import logger`. Plain `print()` in a keyword also ends up in
133
+ the log at INFO, and `*WARN*`-prefixed prints become warnings, but the
134
+ logger is explicit and supports levels. Never log secrets: log a masked value,
135
+ or take a `Secret` argument (see conversion.md). During import and `__init__`
136
+ nothing should be logged (checker: `output_during_import`).
137
+
138
+ ## Threads
139
+
140
+ Only the thread that runs the keyword can log or fail it. Messages that other
141
+ threads send through `logger` are silently dropped, and exceptions raised in
142
+ them never reach RF. Collect results in the worker thread and log or raise in
143
+ the keyword's own thread:
144
+
145
+ ```python
146
+ # file: Parallel.py
147
+ """Run work in threads, report from the keyword thread."""
148
+
149
+ from concurrent.futures import ThreadPoolExecutor
150
+
151
+ from robot.api import logger
152
+ from robot.api.deco import keyword, library
153
+
154
+
155
+ @library(scope="GLOBAL")
156
+ class Parallel:
157
+ """Thread-safe reporting."""
158
+
159
+ @keyword
160
+ def square_all(self, numbers: list[int]) -> list[int]:
161
+ """Square the numbers in parallel and log the result."""
162
+ with ThreadPoolExecutor(max_workers=4) as pool:
163
+ results = list(pool.map(lambda n: n * n, numbers))
164
+ logger.info(f"squares: {results}")
165
+ return results
166
+ ```
167
+
168
+ ## Timeouts
169
+
170
+ A `[Timeout]` or `Test Timeout` stops a running library keyword by raising
171
+ `robot.errors.TimeoutExceeded` (RF 7.3; `robot.errors.TimeoutError` before)
172
+ inside it. Before RF 7.5 that exception derives from `Exception`, so a broad
173
+ `except Exception:` in the keyword swallows it: a retry loop keeps running
174
+ past the timeout (a 4 s loop with a 1 s timeout ran 4.4 s on RF 7.4.2 and
175
+ 1.5 s on 7.5). Catch specific exceptions, or re-raise the timeout first
176
+ (checker: `broad_except`):
177
+
178
+ ```python
179
+ # file: Poller.py
180
+ """A retry loop that does not swallow Robot Framework timeouts."""
181
+
182
+ import time
183
+
184
+ from robot.api.deco import keyword, library
185
+ from robot.errors import TimeoutError as RobotTimeout # TimeoutExceeded on RF 7.3+
186
+
187
+
188
+ @library(scope="GLOBAL")
189
+ class Poller:
190
+ """Polling helpers."""
191
+
192
+ @keyword
193
+ def wait_until_ready(self, attempts: int = 3, interval: float = 0.01) -> int:
194
+ """Retry a check; RF timeouts still stop the loop."""
195
+ for attempt in range(1, attempts + 1):
196
+ try:
197
+ if attempt == attempts:
198
+ return attempt
199
+ raise ConnectionError("not ready")
200
+ except RobotTimeout:
201
+ raise
202
+ except ConnectionError:
203
+ time.sleep(interval)
204
+ raise AssertionError("never ready")
205
+ ```
206
+
207
+ `robot.errors.TimeoutError` exists on every RF 7.x (an alias of
208
+ `TimeoutExceeded` from 7.3), so the import above works on 7.0+.
209
+
210
+ ## Using BuiltIn from a library
211
+
212
+ `from robot.libraries.BuiltIn import BuiltIn` gives access to variables and
213
+ keywords of the running test: `BuiltIn().get_variable_value("${OUTPUT DIR}")`,
214
+ `BuiltIn().run_keyword("Log", "x")`, `BuiltIn().get_library_instance("Browser")`.
215
+ It only works while tests run: calling it in `__init__` or at import time
216
+ fails with `RobotNotRunningError` under libdoc, the checker and language
217
+ servers. Call it inside keywords.
218
+
219
+ `BuiltIn().robot_running` is false under libdoc and the checker, and
220
+ `BuiltIn().dry_run_active` (RF 6.1+) is true during `--dryrun`. Guard side
221
+ effects that must not happen outside a real run:
222
+
223
+ ```python
224
+ # file: Database.py
225
+ """Guarded side effect in __init__."""
226
+
227
+ from robot.api.deco import keyword, library
228
+ from robot.libraries.BuiltIn import BuiltIn
229
+
230
+
231
+ @library(scope="GLOBAL")
232
+ class Database:
233
+ """Connects only during a real run."""
234
+
235
+ def __init__(self, url: str = "sqlite:///:memory:") -> None:
236
+ self._url = url
237
+ self._connected = False
238
+ if BuiltIn().robot_running and not BuiltIn().dry_run_active:
239
+ self._connected = True # open the real connection here
240
+
241
+ @keyword
242
+ def connection_should_be_open(self) -> None:
243
+ """Fail unless the library connected."""
244
+ if not self._connected:
245
+ raise AssertionError(f"not connected to {self._url}")
246
+ ```
247
+
248
+ Better still, connect lazily in the first keyword that needs the connection.