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
robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md
ADDED
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
# Argument conversion from type hints
|
|
2
|
+
|
|
3
|
+
Robot Framework passes every argument from `.robot` data as a string unless it
|
|
4
|
+
is a variable holding another object. A type hint on the Python argument makes
|
|
5
|
+
RF convert the string before the keyword runs and documents the type in libdoc.
|
|
6
|
+
Examples need RF 7.0+ unless a block says otherwise.
|
|
7
|
+
|
|
8
|
+
- [Built-in types](#built-in-types)
|
|
9
|
+
- [Enum and Literal](#enum-and-literal)
|
|
10
|
+
- [Containers and TypedDict](#containers-and-typeddict)
|
|
11
|
+
- [None, unions and their order](#none-unions-and-their-order)
|
|
12
|
+
- [Implicit typing and bool](#implicit-typing-and-bool)
|
|
13
|
+
- [Secret and object (RF 7.4)](#secret-and-object-rf-74)
|
|
14
|
+
- [Custom converters](#custom-converters)
|
|
15
|
+
- [Types without annotations: `types=`](#types-without-annotations-types)
|
|
16
|
+
|
|
17
|
+
## Built-in types
|
|
18
|
+
|
|
19
|
+
| Hint | Accepts (strings) | Notes |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `int` | `42`, `-1`, `0x2A`, `1 000` | spaces and underscores allowed |
|
|
22
|
+
| `float` / `Decimal` | `3.14`, `1e3` | use `Decimal` for money |
|
|
23
|
+
| `bool` | `True`/`yes`/`on`/`1`, `False`/`no`/`off`/`0`/`none`/empty | other strings pass through unchanged |
|
|
24
|
+
| `str` | anything | no conversion |
|
|
25
|
+
| `bytes` | `abc` (Latin-1) | |
|
|
26
|
+
| `datetime` / `date` | `2026-09-28 12:00:00`, epoch seconds | |
|
|
27
|
+
| `timedelta` | `1 minute 30 s`, `90`, `1:30` | RF time format |
|
|
28
|
+
| `Path` | `results/out.json` | |
|
|
29
|
+
| `None` | `None` (case-insensitive) | usually inside a union |
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
# file: Types.py
|
|
33
|
+
"""Built-in conversions."""
|
|
34
|
+
|
|
35
|
+
from datetime import timedelta
|
|
36
|
+
from decimal import Decimal
|
|
37
|
+
from pathlib import Path
|
|
38
|
+
|
|
39
|
+
from robot.api.deco import keyword, library
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@library(scope="GLOBAL")
|
|
43
|
+
class Types:
|
|
44
|
+
"""Show converted values."""
|
|
45
|
+
|
|
46
|
+
@keyword
|
|
47
|
+
def describe(self, count: int, price: Decimal, wait: timedelta, target: Path, enabled: bool) -> str:
|
|
48
|
+
"""Return the converted values as one string."""
|
|
49
|
+
return f"{count + 1}|{price * 2}|{wait.total_seconds()}|{target.name}|{enabled}"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```robotframework
|
|
53
|
+
# file: types.robot
|
|
54
|
+
*** Settings ***
|
|
55
|
+
Library Types
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
*** Test Cases ***
|
|
59
|
+
Strings Become Typed Values
|
|
60
|
+
${text}= Describe 41 1.25 1 minute 30 s results/out.json yes
|
|
61
|
+
Should Be Equal ${text} 42|2.50|90.0|out.json|True
|
|
62
|
+
|
|
63
|
+
Bad Integer Fails Before The Keyword Runs
|
|
64
|
+
Run Keyword And Expect Error *cannot be converted to integer*
|
|
65
|
+
... Describe many 1 1s x no
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Enum and Literal
|
|
69
|
+
|
|
70
|
+
Both restrict an argument to fixed values and match case-insensitively
|
|
71
|
+
(`on` → `ON`). `Literal` (RF 7.0) keeps the plain value; an `Enum` gives the
|
|
72
|
+
member and documents the allowed values once for several keywords. A wrong
|
|
73
|
+
value fails and names the allowed values (`Literal`: "… cannot be converted
|
|
74
|
+
to 'ON' or 'OFF'"; `Enum`: "… Available: 'FAST' and 'SLOW'").
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
# file: Modes.py
|
|
78
|
+
"""Enum and Literal arguments."""
|
|
79
|
+
|
|
80
|
+
from enum import Enum
|
|
81
|
+
from typing import Literal
|
|
82
|
+
|
|
83
|
+
from robot.api.deco import keyword, library
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
class Speed(Enum):
|
|
87
|
+
SLOW = 1
|
|
88
|
+
FAST = 2
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
@library(scope="GLOBAL")
|
|
92
|
+
class Modes:
|
|
93
|
+
"""Fixed-value arguments."""
|
|
94
|
+
|
|
95
|
+
@keyword
|
|
96
|
+
def set_power(self, state: Literal["ON", "OFF"]) -> str:
|
|
97
|
+
"""Return the normalised power state."""
|
|
98
|
+
return state
|
|
99
|
+
|
|
100
|
+
@keyword
|
|
101
|
+
def set_speed(self, speed: Speed) -> int:
|
|
102
|
+
"""Return the numeric value of the speed."""
|
|
103
|
+
return speed.value
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
```robotframework
|
|
107
|
+
# file: modes.robot
|
|
108
|
+
*** Settings ***
|
|
109
|
+
Library Modes
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
*** Test Cases ***
|
|
113
|
+
Values Match Case-Insensitively
|
|
114
|
+
${state}= Set Power on
|
|
115
|
+
Should Be Equal ${state} ON
|
|
116
|
+
${speed}= Set Speed fast
|
|
117
|
+
Should Be Equal ${speed} ${2}
|
|
118
|
+
|
|
119
|
+
Unknown Value Lists The Allowed Ones
|
|
120
|
+
Run Keyword And Expect Error *'ON' or 'OFF'* Set Power maybe
|
|
121
|
+
Run Keyword And Expect Error *Available: 'FAST' and 'SLOW'* Set Speed medium
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Containers and TypedDict
|
|
125
|
+
|
|
126
|
+
`list[int]`, `dict[str, int]`, `tuple[int, ...]` and `set[str]` convert
|
|
127
|
+
Python-literal strings (`[1, 2]`) and also convert the items of a list or
|
|
128
|
+
dictionary variable. `TypedDict` checks the keys and converts each value;
|
|
129
|
+
missing required keys fail.
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
# file: Orders.py
|
|
133
|
+
"""Parametrised containers and TypedDict."""
|
|
134
|
+
|
|
135
|
+
from typing import TypedDict
|
|
136
|
+
|
|
137
|
+
from robot.api.deco import keyword, library
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class Item(TypedDict):
|
|
141
|
+
name: str
|
|
142
|
+
qty: int
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
@library(scope="GLOBAL")
|
|
146
|
+
class Orders:
|
|
147
|
+
"""Container arguments."""
|
|
148
|
+
|
|
149
|
+
@keyword
|
|
150
|
+
def total_quantity(self, quantities: list[int]) -> int:
|
|
151
|
+
"""Sum the quantities."""
|
|
152
|
+
return sum(quantities)
|
|
153
|
+
|
|
154
|
+
@keyword
|
|
155
|
+
def item_label(self, item: Item) -> str:
|
|
156
|
+
"""Return ``<qty> x <name>``."""
|
|
157
|
+
return f"{item['qty']} x {item['name']}"
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
```robotframework
|
|
161
|
+
# file: orders.robot
|
|
162
|
+
*** Settings ***
|
|
163
|
+
Library Orders
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
*** Test Cases ***
|
|
167
|
+
Literal String And List Variable Are Converted
|
|
168
|
+
${total}= Total Quantity [1, 2, 3]
|
|
169
|
+
Should Be Equal ${total} ${6}
|
|
170
|
+
VAR @{strings} 4 5
|
|
171
|
+
${total}= Total Quantity ${strings}
|
|
172
|
+
Should Be Equal ${total} ${9}
|
|
173
|
+
|
|
174
|
+
TypedDict Converts Values
|
|
175
|
+
${label}= Item Label {'name': 'apple', 'qty': '3'}
|
|
176
|
+
Should Be Equal ${label} 3 x apple
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## None, unions and their order
|
|
180
|
+
|
|
181
|
+
`int | None = None` accepts `None` or an integer. RF tries the union members
|
|
182
|
+
from left to right and stops at the first that works; if the argument already
|
|
183
|
+
has one of the member types, it is passed unchanged. So a union with `str`
|
|
184
|
+
never converts a string: every argument from `.robot` data already is one.
|
|
185
|
+
The checker reports this as `union_with_str`.
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
# file: Unions.py
|
|
189
|
+
# Wrong: union_with_str
|
|
190
|
+
"""A union with str never converts strings."""
|
|
191
|
+
|
|
192
|
+
from robot.api.deco import keyword, library
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
@library(scope="GLOBAL")
|
|
196
|
+
class Unions:
|
|
197
|
+
"""Union order."""
|
|
198
|
+
|
|
199
|
+
@keyword
|
|
200
|
+
def add_one(self, value: int | str) -> str:
|
|
201
|
+
"""Returns the type name: ``10`` stays a string."""
|
|
202
|
+
return type(value).__name__
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Put the converting types only (`int | float`), order them from the most to the
|
|
206
|
+
least specific, and keep `str | None` for "text or nothing" (the checker does
|
|
207
|
+
not flag it).
|
|
208
|
+
|
|
209
|
+
## Implicit typing and bool
|
|
210
|
+
|
|
211
|
+
Without a hint, a default value implies the type, but leniently: `def kw(n=3)`
|
|
212
|
+
converts `5` to `5` and passes `abc` through as the string `abc`. `bool`
|
|
213
|
+
conversion also passes unknown strings through (`maybe` stays `maybe`). Neither
|
|
214
|
+
is detected by the checker. Use real hints, and `Literal`/`Enum` when only a
|
|
215
|
+
few values are valid.
|
|
216
|
+
|
|
217
|
+
## Secret and object (RF 7.4)
|
|
218
|
+
|
|
219
|
+
`Secret` (`from robot.api.types import Secret`) marks an argument that only
|
|
220
|
+
accepts `Secret` objects, so the value does not appear in logs. A plain string
|
|
221
|
+
fails ("… must have type 'Secret', got string"). The data creates one from an
|
|
222
|
+
environment variable in the Variables section; read `.value` in the keyword.
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
# file: Vault.py
|
|
226
|
+
# RF 7.4+
|
|
227
|
+
"""Secret arguments."""
|
|
228
|
+
|
|
229
|
+
from robot.api.deco import keyword, library
|
|
230
|
+
from robot.api.types import Secret
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
@library(scope="GLOBAL")
|
|
234
|
+
class Vault:
|
|
235
|
+
"""Uses a secret without logging it."""
|
|
236
|
+
|
|
237
|
+
@keyword
|
|
238
|
+
def password_length(self, password: Secret) -> int:
|
|
239
|
+
"""Return the length of the secret value."""
|
|
240
|
+
return len(password.value)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
```robotframework
|
|
244
|
+
# file: vault.robot
|
|
245
|
+
# RF 7.4+
|
|
246
|
+
*** Settings ***
|
|
247
|
+
Library Vault
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
*** Variables ***
|
|
251
|
+
${PASSWORD: Secret} %{APP_PASSWORD=s3cret}
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
*** Test Cases ***
|
|
255
|
+
Secret From Environment
|
|
256
|
+
${length}= Password Length ${PASSWORD}
|
|
257
|
+
Should Be True ${length} > 0
|
|
258
|
+
|
|
259
|
+
Plain String Is Rejected
|
|
260
|
+
Run Keyword And Expect Error *must have type 'Secret'* Password Length s3cret
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
`object` as a hint (RF 7.4) states "any value, no conversion" explicitly.
|
|
264
|
+
|
|
265
|
+
## Custom converters
|
|
266
|
+
|
|
267
|
+
For a domain type, register a converter function on the library. RF calls it
|
|
268
|
+
only when the argument is not already of that type; it must raise `ValueError`
|
|
269
|
+
on bad input, and RF turns that into a failure naming the argument. Register it
|
|
270
|
+
with `@library(converters={Type: function})` or, in a module library,
|
|
271
|
+
`ROBOT_LIBRARY_CONVERTERS = {Type: function}`.
|
|
272
|
+
|
|
273
|
+
```python
|
|
274
|
+
# file: Shop.py
|
|
275
|
+
"""Custom converter registered with @library(converters=...)."""
|
|
276
|
+
|
|
277
|
+
from dataclasses import dataclass
|
|
278
|
+
|
|
279
|
+
from robot.api.deco import keyword, library
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
@dataclass(frozen=True)
|
|
283
|
+
class Sku:
|
|
284
|
+
"""A stock-keeping unit such as ``AB-1234``."""
|
|
285
|
+
|
|
286
|
+
prefix: str
|
|
287
|
+
number: int
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def parse_sku(value: str) -> Sku:
|
|
291
|
+
"""Convert ``AB-1234``; raise ValueError on anything else."""
|
|
292
|
+
prefix, _, number = value.partition("-")
|
|
293
|
+
if len(prefix) != 2 or not prefix.isalpha() or not number.isdigit():
|
|
294
|
+
raise ValueError(f"expected an SKU like 'AB-1234', got '{value}'")
|
|
295
|
+
return Sku(prefix.upper(), int(number))
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
@library(scope="GLOBAL", converters={Sku: parse_sku})
|
|
299
|
+
class Shop:
|
|
300
|
+
"""Keywords that take SKUs."""
|
|
301
|
+
|
|
302
|
+
@keyword
|
|
303
|
+
def sku_number(self, sku: Sku) -> int:
|
|
304
|
+
"""Return the numeric part of ``sku``."""
|
|
305
|
+
return sku.number
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
```robotframework
|
|
309
|
+
# file: shop.robot
|
|
310
|
+
*** Settings ***
|
|
311
|
+
Library Shop
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
*** Test Cases ***
|
|
315
|
+
String Becomes Sku
|
|
316
|
+
${number}= Sku Number ab-1234
|
|
317
|
+
Should Be Equal ${number} ${1234}
|
|
318
|
+
|
|
319
|
+
Converter Error Names The Argument
|
|
320
|
+
Run Keyword And Expect Error *'sku'*expected an SKU like 'AB-1234'* Sku Number 1234
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
`assets/examples/converters.py` shows the module-library form
|
|
324
|
+
(`ROBOT_LIBRARY_CONVERTERS`) with a `Money` type.
|
|
325
|
+
|
|
326
|
+
## Types without annotations: `types=`
|
|
327
|
+
|
|
328
|
+
`@keyword(types={"count": int})` (or a list in argument order) sets types when
|
|
329
|
+
annotations are not possible, for example on generated functions. Annotations
|
|
330
|
+
are preferred.
|
|
331
|
+
|
|
332
|
+
```python
|
|
333
|
+
# file: Legacy.py
|
|
334
|
+
"""Types given through the keyword decorator."""
|
|
335
|
+
|
|
336
|
+
from robot.api.deco import keyword, library
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
@library(scope="GLOBAL")
|
|
340
|
+
class Legacy:
|
|
341
|
+
"""Old-style keyword."""
|
|
342
|
+
|
|
343
|
+
@keyword(types={"count": int})
|
|
344
|
+
def repeat_word(self, word, count):
|
|
345
|
+
"""Repeat ``word`` ``count`` times."""
|
|
346
|
+
return word * count
|
|
347
|
+
```
|
robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Listeners
|
|
2
|
+
|
|
3
|
+
A listener is a Python class or module whose methods Robot Framework calls
|
|
4
|
+
while a run progresses. Listener API version 3 (the default from RF 7.0)
|
|
5
|
+
passes the running data and result model objects, so a listener can read and
|
|
6
|
+
change them. Examples need RF 7.0+ unless a block says otherwise.
|
|
7
|
+
|
|
8
|
+
- [Listener API v3 methods](#listener-api-v3-methods)
|
|
9
|
+
- [Registering a listener](#registering-a-listener)
|
|
10
|
+
- [A library that is also a listener](#a-library-that-is-also-a-listener)
|
|
11
|
+
- [Priority](#priority)
|
|
12
|
+
- [Changing results](#changing-results)
|
|
13
|
+
- [Rules of thumb](#rules-of-thumb)
|
|
14
|
+
|
|
15
|
+
## Listener API v3 methods
|
|
16
|
+
|
|
17
|
+
| Method | Called |
|
|
18
|
+
|---|---|
|
|
19
|
+
| `start_suite(data, result)` / `end_suite(data, result)` | around each suite; `start_suite` may modify `data` (add or filter tests) |
|
|
20
|
+
| `start_test(data, result)` / `end_test(data, result)` | around each test; `end_test` may change `result.status` and `result.message` |
|
|
21
|
+
| `start_keyword(data, result)` / `end_keyword(data, result)` | around every keyword and control structure (RF 7.0+; also `start_library_keyword`, `start_user_keyword`, `start_for`, …) |
|
|
22
|
+
| `log_message(message)` / `message(message)` | a log message / a system message |
|
|
23
|
+
| `library_import`, `resource_import`, `variables_import` | after an import |
|
|
24
|
+
| `output_file(path)`, `log_file`, `report_file`, `xunit_file`, `debug_file` | when an output file is written |
|
|
25
|
+
| `close()` | once at the end (for a library listener: when the library goes out of scope) |
|
|
26
|
+
|
|
27
|
+
Every method is optional; implement only the ones you need. Version 2
|
|
28
|
+
listeners (name and attribute-dict arguments) still work with
|
|
29
|
+
`ROBOT_LISTENER_API_VERSION = 2`, but new code uses version 3.
|
|
30
|
+
|
|
31
|
+
## Registering a listener
|
|
32
|
+
|
|
33
|
+
On the command line, by module or class name on the python-path (or a file
|
|
34
|
+
path). Arguments follow after colons and reach `__init__` as strings:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv run robot --pythonpath libraries --listener ResultListener tests/
|
|
38
|
+
uv run robot --pythonpath libraries --listener ResultListener:summary.json tests/
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
In `robot.toml` the same goes into `listeners = ["ResultListener:summary.json"]`.
|
|
42
|
+
`assets/examples/ResultListener.py` is a complete listener that writes a JSON
|
|
43
|
+
summary into the output directory at `close`.
|
|
44
|
+
|
|
45
|
+
## A library that is also a listener
|
|
46
|
+
|
|
47
|
+
`@library(listener="SELF")` (or `ROBOT_LIBRARY_LISTENER = self` in `__init__`)
|
|
48
|
+
makes the library instance a listener for the suites that import it. With
|
|
49
|
+
`@library`, listener methods such as `end_test` do not become keywords, and
|
|
50
|
+
the checker does not flag them. Without `@library` they are keywords (checker:
|
|
51
|
+
`listener_method_exposed`).
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
# file: Timing.py
|
|
55
|
+
"""Library listener: records test durations of the importing suite."""
|
|
56
|
+
|
|
57
|
+
from robot.api.deco import keyword, library
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
@library(scope="SUITE", listener="SELF")
|
|
61
|
+
class Timing:
|
|
62
|
+
"""Collects the duration of each finished test."""
|
|
63
|
+
|
|
64
|
+
def __init__(self) -> None:
|
|
65
|
+
self._durations: dict[str, float] = {}
|
|
66
|
+
|
|
67
|
+
def end_test(self, data, result) -> None:
|
|
68
|
+
self._durations[result.name] = result.elapsed_time.total_seconds()
|
|
69
|
+
|
|
70
|
+
@keyword
|
|
71
|
+
def finished_test_count(self) -> int:
|
|
72
|
+
"""Number of tests of this suite that have finished so far."""
|
|
73
|
+
return len(self._durations)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```robotframework
|
|
77
|
+
# file: timing.robot
|
|
78
|
+
*** Settings ***
|
|
79
|
+
Library Timing
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
*** Test Cases ***
|
|
83
|
+
First
|
|
84
|
+
No Operation
|
|
85
|
+
|
|
86
|
+
Second Sees The First As Finished
|
|
87
|
+
${count}= Finished Test Count
|
|
88
|
+
Should Be Equal ${count} ${1}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Priority
|
|
92
|
+
|
|
93
|
+
With several listeners, `ROBOT_LISTENER_PRIORITY = <number>` (RF 7.1+) orders
|
|
94
|
+
them: higher numbers are called first for every event. Without it, listeners
|
|
95
|
+
run in the order they were registered.
|
|
96
|
+
|
|
97
|
+
## Changing results
|
|
98
|
+
|
|
99
|
+
In `end_test`, set `result.status` to `"PASS"`, `"FAIL"` or `"SKIP"` and
|
|
100
|
+
adjust `result.message`; the change reaches `output.xml`, the log, the report
|
|
101
|
+
and the exit code (skipped tests do not fail the run). Keep such rules narrow
|
|
102
|
+
and explicit, for example driven by a tag, and say in the message why the
|
|
103
|
+
status changed.
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
# file: KnownIssues.py
|
|
107
|
+
# check: skip (a listener, not a library)
|
|
108
|
+
"""Listener: failing tests tagged known-issue are reported as SKIP."""
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class KnownIssues:
|
|
112
|
+
"""Turns failures of tests tagged ``known-issue`` into skips."""
|
|
113
|
+
|
|
114
|
+
ROBOT_LISTENER_API_VERSION = 3
|
|
115
|
+
|
|
116
|
+
def __init__(self, tag: str = "known-issue") -> None:
|
|
117
|
+
self._tag = tag
|
|
118
|
+
|
|
119
|
+
def end_test(self, data, result) -> None:
|
|
120
|
+
if result.failed and self._tag in result.tags:
|
|
121
|
+
result.message = f"Skipped by KnownIssues ({self._tag}): {result.message}"
|
|
122
|
+
result.status = "SKIP"
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
```robotframework
|
|
126
|
+
# file: known_issues.robot
|
|
127
|
+
# run: --listener KnownIssues
|
|
128
|
+
*** Test Cases ***
|
|
129
|
+
Tracked Bug
|
|
130
|
+
[Tags] known-issue
|
|
131
|
+
Fail Ticket 123 is not fixed yet
|
|
132
|
+
|
|
133
|
+
Healthy Feature
|
|
134
|
+
Should Be Equal ${{ 2 * 2 }} ${4}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
With the listener the run exits 0 (1 passed, 1 skipped); without it, 1.
|
|
138
|
+
`KnownIssues` is a listener, not a library: its listener methods would be
|
|
139
|
+
keywords if it were imported with `Library`.
|
|
140
|
+
|
|
141
|
+
## Rules of thumb
|
|
142
|
+
|
|
143
|
+
- Keep listener methods fast; they run for every test or keyword.
|
|
144
|
+
- Do not raise from a listener: RF reports the error and continues, but the
|
|
145
|
+
change you wanted is lost.
|
|
146
|
+
- Use `robot.api.logger` from listener methods only in the main thread.
|
|
147
|
+
- `start_keyword` / `end_keyword` fire for every keyword, including BuiltIn
|
|
148
|
+
ones; filter on `data.name` or `data.owner` early.
|
|
149
|
+
- A listener that posts to chat or a webhook reads the URL and token from
|
|
150
|
+
environment variables, never from the repository.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Documentation, packaging and tests
|
|
2
|
+
|
|
3
|
+
How libdoc reads a library, how to document and version it, how to ship it as
|
|
4
|
+
a package, and how to test it. Examples need RF 7.0+ unless a block says
|
|
5
|
+
otherwise.
|
|
6
|
+
|
|
7
|
+
- [libdoc output](#libdoc-output)
|
|
8
|
+
- [Writing docstrings](#writing-docstrings)
|
|
9
|
+
- [Doc formats](#doc-formats)
|
|
10
|
+
- [Versioning](#versioning)
|
|
11
|
+
- [Package layout](#package-layout)
|
|
12
|
+
- [Dependencies](#dependencies)
|
|
13
|
+
- [Testing a library](#testing-a-library)
|
|
14
|
+
|
|
15
|
+
## libdoc output
|
|
16
|
+
|
|
17
|
+
libdoc imports the library (running its import and `__init__` code, like the
|
|
18
|
+
checker) and writes its documentation:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
uv run libdoc libraries/Inventory.py docs/Inventory.html
|
|
22
|
+
uv run libdoc libraries/Inventory.py docs/Inventory.json
|
|
23
|
+
uv run libdoc --pythonpath libraries Inventory list
|
|
24
|
+
uv run libdoc --pythonpath libraries Inventory show "Add Item"
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The output format follows the file extension (`.html`, `.xml`, `.json`,
|
|
28
|
+
`.libspec`); `list` and `show` print to the console. With robotcode installed,
|
|
29
|
+
`robotcode doc keywords libraries/Inventory.py` and `robotcode doc keyword
|
|
30
|
+
libraries/Inventory.py "Add Item"` print the same data as Markdown, using the
|
|
31
|
+
project's `robot.toml`. Commit generated HTML only when the project publishes
|
|
32
|
+
it; editors and language servers read the library directly.
|
|
33
|
+
|
|
34
|
+
## Writing docstrings
|
|
35
|
+
|
|
36
|
+
- The class (or module) docstring is the library introduction; the
|
|
37
|
+
`__init__` docstring documents the import arguments.
|
|
38
|
+
- A keyword's first docstring line is its short doc in listings; keep it one
|
|
39
|
+
sentence that starts with a verb.
|
|
40
|
+
- Google-style `Args:` sections are fine; libdoc shows the types from the
|
|
41
|
+
hints, so do not repeat them in prose.
|
|
42
|
+
- In the default `ROBOT` format, `` `Other Keyword` `` links to a keyword,
|
|
43
|
+
``` ``code`` ``` is inline code, `*bold*` and `_italic_` work, and a table
|
|
44
|
+
row such as `| Add Item | apple | 3 |` shows an example call.
|
|
45
|
+
- A library without a docstring gets the placeholder "Documentation for
|
|
46
|
+
library ``Name``." (checker: `library_doc_missing`); a keyword without one
|
|
47
|
+
has an empty doc (checker: `missing_doc`).
|
|
48
|
+
|
|
49
|
+
## Doc formats
|
|
50
|
+
|
|
51
|
+
| Format | Set with | Notes |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `ROBOT` (default) | nothing | RF's own light markup |
|
|
54
|
+
| `HTML` | `ROBOT_LIBRARY_DOC_FORMAT = "HTML"` or `@library(doc_format="HTML")` | raw HTML |
|
|
55
|
+
| `TEXT` | `"TEXT"` | no formatting |
|
|
56
|
+
| `REST` | `"REST"` | needs the `docutils` package |
|
|
57
|
+
| `MARKDOWN` | `"MARKDOWN"` | RF 7.5+; needs the `markdown` package (RF 7.4 rejects it as an invalid format) |
|
|
58
|
+
|
|
59
|
+
Keep one format per library.
|
|
60
|
+
|
|
61
|
+
## Versioning
|
|
62
|
+
|
|
63
|
+
`@library(version="1.2.0")` or `ROBOT_LIBRARY_VERSION = "1.2.0"` shows the
|
|
64
|
+
version in libdoc, in the log's import message and in the checker output. For
|
|
65
|
+
a packaged library, read it from the package metadata so there is one source:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
# file: Versioned.py
|
|
69
|
+
"""Library version from one place."""
|
|
70
|
+
|
|
71
|
+
from robot.api.deco import keyword, library
|
|
72
|
+
|
|
73
|
+
__version__ = "1.2.0"
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
@library(scope="GLOBAL", version=__version__)
|
|
77
|
+
class Versioned:
|
|
78
|
+
"""A library that reports its version."""
|
|
79
|
+
|
|
80
|
+
@keyword
|
|
81
|
+
def library_version(self) -> str:
|
|
82
|
+
"""Return the library version."""
|
|
83
|
+
return __version__
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Package layout
|
|
87
|
+
|
|
88
|
+
A project library is one file in `libraries/`. A library shared between
|
|
89
|
+
projects becomes a package:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
mylibrary/
|
|
93
|
+
├── pyproject.toml # name, version, dependencies = ["robotframework>=7"]
|
|
94
|
+
├── src/mylibrary/
|
|
95
|
+
│ ├── __init__.py # the library class, named like the package: class mylibrary
|
|
96
|
+
│ │ # or, RF 7.2+, one @library class with any name
|
|
97
|
+
│ ├── keywords/… # components (plain classes, or PythonLibCore components)
|
|
98
|
+
│ └── resources/common.resource
|
|
99
|
+
└── tests/
|
|
100
|
+
├── unit/ # pytest
|
|
101
|
+
└── acceptance/ # .robot suites that import the library by name
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
- Import it as `Library mylibrary` once installed; `Library mylibrary.Client`
|
|
105
|
+
selects a class inside it.
|
|
106
|
+
- Ship `.resource` files as package data (setuptools `package-data`, or
|
|
107
|
+
hatch's default include) and import them through the python-path:
|
|
108
|
+
`Resource mylibrary/resources/common.resource`.
|
|
109
|
+
- Keep the package importable without side effects: libdoc, the checker,
|
|
110
|
+
editors and `--dryrun` all import it.
|
|
111
|
+
|
|
112
|
+
## Dependencies
|
|
113
|
+
|
|
114
|
+
Declare runtime dependencies in the package's `pyproject.toml`, and add them
|
|
115
|
+
to a project with its tool (`uv add <package>`; Poetry or pip in a venv
|
|
116
|
+
otherwise; see rf-setup). An import error at load time shows up as the
|
|
117
|
+
checker's `import_failed` finding with the `ModuleNotFoundError` text.
|
|
118
|
+
|
|
119
|
+
## Testing a library
|
|
120
|
+
|
|
121
|
+
1. The checker: `uv run python scripts/check_library.py libraries/*.py` (the
|
|
122
|
+
script path is relative to the rf-python-library skill directory, the
|
|
123
|
+
library paths to the project root) finds RF-specific defects without
|
|
124
|
+
running tests.
|
|
125
|
+
2. pytest for logic that does not need RF: instantiate the class and call the
|
|
126
|
+
methods. Raising `AssertionError` is testable with `pytest.raises`.
|
|
127
|
+
3. Acceptance suites in `.robot` files exercise the library the way users
|
|
128
|
+
call it, including conversion errors (`Run Keyword And Expect Error`).
|
|
129
|
+
4. In CI, run the suites with `--pythonpath libraries` (or the `robot.toml`
|
|
130
|
+
python-path) and the checker on every library.
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
# file: test_inventory_logic.py
|
|
134
|
+
# check: skip (a pytest module, not a library)
|
|
135
|
+
"""pytest for library logic without Robot Framework running."""
|
|
136
|
+
|
|
137
|
+
import pytest
|
|
138
|
+
|
|
139
|
+
from ExampleLibrary import ExampleLibrary
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def test_add_item_counts() -> None:
|
|
143
|
+
lib = ExampleLibrary()
|
|
144
|
+
assert lib.add_item("apple", 2) == 2
|
|
145
|
+
assert lib.add_item("apple", 3) == 5
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def test_count_mismatch_fails() -> None:
|
|
149
|
+
lib = ExampleLibrary()
|
|
150
|
+
with pytest.raises(AssertionError, match="expected 1"):
|
|
151
|
+
lib.item_count_should_be("apple", 1)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The pytest example uses `assets/examples/ExampleLibrary.py`; run it with that
|
|
155
|
+
directory on `PYTHONPATH`.
|