# 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.

[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![Playwright](https://img.shields.io/badge/Playwright-E2E-2EAD33?logo=playwright&logoColor=white)](https://playwright.dev/)
[![Streamlit](https://img.shields.io/badge/UI-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io/)

> 文档与代码同步日期：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。

## 主流程

```mermaid
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](LLM_PROVIDERS.md)。

Windows 一键安装：

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

也可以手动安装：

```powershell
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 调试界面：

```bat
.\run_app.bat
```

本机 HTTP MCP：

```bat
.\run_mcp_server_local.bat
```

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

```bat
.\run_mcp_server_http.bat
```

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

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

最小本地配置示例：

```dotenv
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 和回调地址：

```dotenv
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` 中配置：

```dotenv
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`：

```json
{
  "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 传输和工具发现：

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

代码和 Agent 回归：

```powershell
python -m pytest -q agent
```

## 项目结构

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

## 进一步阅读

- [技术细节与运行契约](docs/TECHNICAL_DETAILS.md)
- [项目上下文与职责边界](docs/PROJECT_CONTEXT.md)
- [MCP 外部平台集成](docs/MCP_EXTERNAL_PLATFORM_INTEGRATION.md)
- [固定 Agent 部署](docs/PLATFORM_MCP_DEPLOYMENT.md)
- [平台适配说明](docs/AGENTIC_TEST_PLATFORM_ADAPTATION.md)
- [Harness 工程目标](docs/HARNESS_ENGINEERING_GOAL.md)
- [P0 自主恢复规范](docs/P0_FINAL.md)
- [Agent 执行架构与持续自修复契约](docs/DELIVERY_STABILIZATION_CHANGELOG_2026-08-12.md)