内容
> 🇫🇷 法语版本： [README.fr.md](README.fr.md)
# 测试代理
**适用于Robot Framework的通用测试代理 — 通过 [rf-mcp](https://github.com/manykarim/rf-mcp) （RobotMCP）服务器驱动的实时应用程序，实现计划、生成、修复的功能。**
技术无关：这些代理适用于Robot Framework可以加载的任何库 — Web（Browser/Playwright，SeleniumLibrary）、HTTP API（RequestsLibrary）、移动端（AppiumLibrary）、数据库等。它们将Playwright Test Agents的理念（计划器/生成器/修复器）移植到Robot Framework生态系统中，从SAPFX项目（同一作者）推广而来。许可证：Apache-2.0。
```mermaid
flowchart TB
APP(["实时应用程序 — Web · API · 移动端"])
MCP{{"rf-mcp · 感知 → 执行 → 感知"}}
subgraph CYCLE ["计划 → 生成 → 修复"]
direction LR
PLAN["<b>rf-planner</b><br/>/rf-plan"]
SPEC["规格/<br/><b>业务计划</b><br/>真实来源"]
GEN["<b>rf-generator</b><br/>/rf-generate"]
CODE["测试/robot/ + 资源/<br/>套件 · 页面对象"]
HEAL["<b>rf-healer</b><br/>/rf-heal"]
PLAN ==>|"探索<br/>和观察"| SPEC
SPEC ==>|"每一步<br/>实时重放"| GEN
GEN ==> CODE
CODE ==>|"套件变红"| HEAL
HEAL ==>|"修复<br/>资源/"| CODE
GEN -.->|"记录差异"| SPEC
HEAL -.->|"过时规格<br/>修复日志"| PLAN
end
APP <--> MCP
MCP -.-> CYCLE
classDef agent fill:#4f46e5,stroke:#3730a3,color:#ffffff
classDef artefact fill:#e0e7ff,stroke:#6366f1,color:#1e1b4b
classDef live fill:#059669,stroke:#047857,color:#ffffff
class PLAN,GEN,HEAL agent
class SPEC,CODE artefact
class APP,MCP live
style CYCLE fill:transparent,stroke:#94a3b8,stroke-dasharray:5 5
```
实线箭头表示循环；虚线箭头表示反馈环路，使计划保持一致 — 生成器记录现实与计划的偏差，修复器在业务流程本身发生变化时标记规格过期，每个修复都会记录在修复日志中，供计划器下次读取。
## 三个代理
| 代理 | 命令 | 功能 |
|-------|---------|--------------|
| **rf-planner** | `/rf-plan` | 通过rf-mcp（感知 → 执行 → 感知，ARIA快照，实时API响应）探索实时应用程序，并编写业务可读的测试计划，位于`specs/`下。计划中的每个事实都是实时观察到的，绝不假设。 |
| **rf-generator** | `/rf-generate` | 将一个`specs/`计划转换为可运行的`.robot`套件。其定义原则：**在文件中的步骤在实时执行之前绝不会落地**，通过rf-mcp。缺少的业务关键词会添加到资源层（页面对象），绝不会内联在测试中。 |
| **rf-healer** | `/rf-heal` | 通过修复**自动化层**（`resources/`），而绝不削弱测试所证明的内容，来修复失败的套件。定位器漂移、时间、数据漂移和真正的函数变化都得到各自的处理；真正的流程变化会回到计划器。 |
`/rf-generate-all` 将生成器链接到每个合格的规格（顺序 — 共享页面对象和一个实时会话不并行）。
循环由机械防护和显式反馈环路关闭：
- **出处** — 每个生成的套件都嵌入了其源规格的内容哈希（+日期）；`python scripts/check_spec_sync.py`在规格更改而未重新生成时失败 — **计划是真实来源**。
- **约定** — `python scripts/check_conventions.py`机械地拒绝测试体中的原始定位器和任何`Sleep`（生成器门控，`.claude/settings.json`中的后编辑钩子，CI）。
- **反馈环路** — 修复器标记功能更改的规格`> **状态：过期（日期）**`（阻止防护直到计划器重新探索）；生成器在重新标记之前记录现实/规格的偏差（「生成时偏差」）；每个修复都记录在`docs/heal-journal.md`中，即计划器读取的漂移内存。
## 不可商量的约定（代理强制执行）
1. **测试不包含原始定位器。** CSS/XPath/元素ID位于`resources/page_objects/*.resource`（每个页面/屏幕/API域一个页面对象）或`variables/locators.py`；测试使用业务语言。
2. **绝不使用`Sleep`等待。** 只有真正的同步（`Wait For Elements State`，`Wait Until Element Is Visible`，`Wait Until Keyword Succeeds`）。
3. **强大的断言。** 稳定的ID，ARIA角色 + 可访问名称，`data-testid`，HTTP状态码，JSON字段名称，计数 — 绝不使用本地化显示文本，当存在稳定的锚点时。
4. **绝不伪造定位器。** 每个定位器在提交之前都是实时观察/探测的。
5. **凭证绝不落地文件。** RF 7.4+ 类型`Secret:`命令行变量，即使在TRACE下也掩盖。
## 布局
```text
.claude/agents/ rf-planner / rf-generator / rf-healer （规范定义）
.claude/commands/ /rf-plan /rf-generate /rf-generate-all /rf-heal
.claude/settings.json 后编辑钩子运行两个防护
.mcp.json rf-mcp服务器声明（项目范围）
specs/ 业务测试计划（真实来源）
resources/ common.resource + page_objects/ — 代理编写和修复的层
variables/ env_<env>.yaml, 共享locators.py （绝不凭证）
tests/robot/ 生成的套件 — api/ · ui/web/ · ui/mobile/ · cross/
tests/unit/ pytest测试防护脚本
scripts/ check_spec_sync.py · check_conventions.py · hook_guards.py
docs/ heal-journal.md （漂移内存） · validation-live.md （运行手册）
.github/workflows/ CI：单元测试 + 两个防护
results/ robot输出（gitignored）
```
## 快速开始
```bash
python -m venv .venv && .venv\Scripts\activate # Windows
pip install -r requirements.txt # 取消注释您通道的库
rfbrowser init # 仅当您启用robotframework-browser
```
在Claude Code（或任何MCP-capable代理主机）中打开文件夹：`.mcp.json`声明rf-mcp服务器。然后：
/rf-plan https://myapp.example.com的登录流程
/rf-generate specs/login-flow.md
/rf-heal tests/robot/ui/web/login_flow.robot
## 与SAPFX的关系
这些代理的SAP特定化身（SAP GUI感知关键词，UI5定位器引擎，修复遥测）存在于SAPFX项目中，并停留在那里。本项目是**通用核心**：rf-mcp的通用合约仅（`manage_session`，`execute_step`，`get_session_state`，`get_locator_guidance`，`run_test_suite`…），不需要应用程序特定的插件。
