Testing Agent：Playwright UI 测试引擎

自愈式 UI/API 自动化测试 Agent：Planner 探路、Generator 生成 Action DSL 与 Playwright TS、Runner 验证、Healer 自愈恢复，MCP 对接外部测试平台，支持多 Provider 故障切换。
Self-healing UI/API testing agent: plan → generate → run → heal, MCP-integrated, with provider failover.

文档与代码同步日期：2026-08-12。

本仓库实现固定 Agent 层，负责测试计划、代码生成、浏览器执行和自动恢复。外部 agentic-test-platform 负责持久化项目、环境、账号、用例、版本、运行记录和报告。

核心特性

• 全自动编排：Architect 拆分宽泛需求 → Planner 探索 → Generator 生成 → Runner 确定性执行，最终 PASS/FAIL 以 Runner 为准。
• 自愈闭环：失败后自动归因（Triage），只选择一个恢复所有者（Planner / Generator / Healer），持续恢复直到 Local PASS 或明确阻塞，拒绝重复候选。
• Provider 故障切换：openai / openai_http / deepseek 任一故障时同阶段自动 Failover，不重启页面探索。
• MCP 外部平台集成：作为带 Bearer Token 的 Streamable HTTP MCP Server 供测试平台批量调用，子任务结果增量发布。
• 敏感信息脱敏：面向测试人员的失败摘要自动脱敏为可执行的中文报告。
• API 测试独立通道：API Parser → API Planner → Karate Generator → 平台原生 Runner。

主流程

flowchart LR
    A[平台测试用例] --> B[Architect<br/>需求拆分]
    B --> C[Planner<br/>探索页面与计划]
    C --> D[Generator<br/>Action DSL + Playwright TS]
    D --> E[Local Runner<br/>确定性执行]
    E -->|PASS| G[Platform Run / Report]
    E -->|FAIL| F[Triage<br/>自动归因]
    F -->|Planner 恢复| C
    F -->|Generator 恢复| D
    F -->|Healer 修复| H[Healer<br/>证据修复]
    H --> E
    F -->|明确阻塞| I[停止并报告]

阶段	作用
Planner	探索当前页面，理解业务目标，生成 Markdown 测试计划。
Generator	根据计划生成 Action DSL 和 Playwright TypeScript。
Runner	确定性执行测试并收集结果；最终 PASS/FAIL 以 Runner 为准。
Healer	根据最新失败证据修复定位、参数或局部代码，再交给 Local Runner 重跑。

Architect 只用于把宽泛需求拆成套件；平台已经提供单用例边界时不会重复拆分。Full Auto 使用单层成功优先恢复：默认最多验证 50 个不同 Candidate，每个 Failure Episode 最多 20 个 Proposal；重复 Candidate 不会再次进入 Runner。只有最终 Local PASS 后才调用平台 Run/Report。API 测试走独立的 API Parser → API Planner → Karate Generator → 平台 Runner 流程。

安装

要求：Python 3.11+、Node.js 20+、npm，以及所选 LLM Provider 的 API Key。对外支持的 Provider 只有 openai、openai_http 和 deepseek，配置方式见 LLM_PROVIDERS.md。

Windows 一键安装：

.\setup.bat
copy .env.example .env
npx.cmd playwright install chromium

也可以手动安装：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
npm install
npx.cmd playwright install chromium

不要提交 .env、Token、Cookie、storage state 或运行时证据。

启动 Agent

本地 Streamlit 调试界面：

.\run_app.bat

本机 HTTP MCP：

.\run_mcp_server_local.bat

按 .env 中的私网地址启动 LAN HTTP MCP：

.\run_mcp_server_http.bat

stdio 模式由 MCP Client 直接启动，不要把它当成交互式控制台：

{
  "command": "python",
  "args": ["-m", "agent.mcp_server"],
  "cwd": "M:\\Desktop\\Merge\\Testing-Agent-main"
}

最小本地配置示例：

LLM_PROVIDER=openai
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.5

AGENT_RUNTIME_ROOT=D:\AgentRuntime
AGENT_MCP_TRANSPORT=stdio
AGENT_MCP_HOST=127.0.0.1
AGENT_MCP_PORT=8000
AGENT_MCP_PATH=/mcp
AGENT_MCP_PUBLIC_URL=http://127.0.0.1:8000
AGENT_MCP_CLIENT_TOKENS_JSON={}
AGENT_PLATFORM_TARGETS_JSON={}

HTTP 启动脚本会为当前进程覆盖传输方式；LAN 部署应使用 Bearer Token、HTTPS 或可信内网，并配置可写的 AGENT_RUNTIME_ROOT。

连接测试平台

1. 在 Agent 电脑登记平台

在 Agent 的 .env 中为每个平台配置独立 Token 和回调地址：

AGENT_MCP_REMOTE_PLATFORM_ONLY=true
AGENT_MCP_CLIENT_TOKENS_JSON={"tester-a":"replace-with-random-token"}
AGENT_PLATFORM_TARGETS_JSON={"tester-a":{"base_url":"https://tester-a.example.com"}}
AGENT_MCP_PUBLIC_URL=http://agent-host:8000

tester-a 必须同时出现在两个 JSON 中。平台地址需要能被 Agent 电脑访问；Token 和平台侧 headers 只保留在服务端。

2. 在测试平台配置 MCP Client

在平台的 .env.local 中配置：

REMOTE_AGENT_MCP_URL=https://agent.example.com/mcp
REMOTE_AGENT_MCP_AUTH_TOKEN=replace-with-tester-a-token
REMOTE_AGENT_PLATFORM_TARGET_ID=tester-a
REMOTE_AGENT_MCP_TIMEOUT_MS=15000
REMOTE_AGENT_ALLOW_INSECURE_HTTP=false

启动 Agent HTTP MCP 后，平台先调用 get_agent_health，再调用 start_platform_batch_auto：

{
  "platform_target_id": "tester-a",
  "platform_project_id": "project-id",
  "platform_environment_id": "environment-id",
  "platform_account_id": "account-id",
  "cases": [{"platform_case_id": "case-id"}],
  "browser_headless": true,
  "stop_on_failure": false
}项目结构

```text
agent/              Agent 层实现（编排、计划、生成、执行、恢复、MCP 服务）
tests/              Playwright helper 与 helper 行为测试
docs/               架构、部署与运行契约文档
scripts/            MCP 平台冒烟脚本
app.py              Streamlit 调试工作台
run_*.bat           Windows 启动脚本

工具会立即返回 `job_id`。平台持续调用：

```json
{"job_id":"job-id"}

status=completed 只表示 Job 已结束；业务结果还要检查 result.success=true 以及每项 platform_run_status=passed。批量运行中，已完成的子用例会增量出现在 result.cases 中。完成后可调用 get_run_report 查看报告。

3. 连接自检

只检查 MCP 传输和工具发现：

python scripts/mcp_platform_smoke.py tools
python scripts/mcp_platform_smoke.py smoke

代码和 Agent 回归：

python -m pytest -q agent

项目结构

agent/              Agent 层实现（编排、计划、生成、执行、恢复、MCP 服务）
tests/              Playwright helper 与 helper 行为测试
docs/               架构、部署与运行契约文档
scripts/            MCP 平台冒烟脚本
app.py              Streamlit 调试工作台
run_*.bat           Windows 启动脚本

进一步阅读

• 技术细节与运行契约
• 项目上下文与职责边界
• MCP 外部平台集成
• 固定 Agent 部署
• 平台适配说明
• Harness 工程目标
• P0 自主恢复规范
• Agent 执行架构与持续自修复契约