# AI browser automatic recognition test

**Repository Path**: maoning325/ai-browser-automatic-recognition-test

## Basic Information

- **Project Name**: AI browser automatic recognition test
- **Description**: 本项目是一个本地 CLI 工具，用来把现有 Excel 测试用例转换成浏览器自动化脚本并执行，最终输出执行报告和缺陷清单。
最小输入只有 3 项：测试用例 Excel、系统登录地址、账号密码。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 浏览器自动化识别测试 CLI

本项目用于把 Excel 中的人工测试用例转换为可审计的 Playwright 自动化脚本。工具会登录目标后台系统，探索页面、SPA 路由、iframe、弹窗、抽屉、tab、筛选区、表格和行级操作，生成结构化语义地图，再匹配用例、生成并执行脚本，最后输出运行报告、人工审查报告、自动化工作簿和缺陷工作簿。

当前架构以 Playwright 规则探索和确定性执行为主，Browser-use Agent Assist 默认作为探索和低置信度匹配的辅助层，LLM 只在意图解析、UI 匹配、iframe 选择和失败诊断等低置信度场景做补强。

## 安装

```bash
npm install
npm run playwright:install
```

`npm install` 只安装 Node.js 依赖。Playwright 浏览器二进制需要通过 `npm run playwright:install` 安装，或在离线环境中提前准备浏览器缓存。

## 离线运行 Playwright

隔离环境可以运行，但必须提前准备好 Playwright 需要的浏览器二进制。

常见做法：

1. 在联网机器执行 `npm install` 和 `npm run playwright:install`。
2. 把项目目录、`node_modules` 和 Playwright 浏览器缓存目录迁移到隔离环境。
3. 在隔离环境保持相同 Node.js 版本，并配置浏览器缓存路径。

PowerShell 示例：

```powershell
$env:PLAYWRIGHT_BROWSERS_PATH = "C:\path\to\playwright-browsers"
```

如果 `node_modules` 中已有依赖但仍在联网下载 Chrome，通常说明缺少 Playwright 浏览器缓存，或当前运行用户找不到缓存目录。`node_modules` 里有 Playwright 包不等于已经有 Chromium 浏览器二进制。

## 运行命令

```bash
npm run cli -- \
  --input /absolute/path/to/cases.xlsx \
  --base-url http://127.0.0.1:3000/login \
  --username tester \
  --password secret \
  --output-dir /absolute/path/to/output \
  --max-pages 5 \
  --max-contexts-per-page 5 \
  --run-id demo-run
```

必填参数：

| 参数 | 含义 |
| --- | --- |
| `--input` | 测试用例 Excel 文件路径。未指定 sheet 时优先读取 `原始用例`，不存在则兜底读取第一个工作表。 |
| `--base-url` | 目标系统登录页地址。 |
| `--username` | 登录用户名。 |
| `--password` | 登录密码。 |

可选参数：

| 参数 | 默认值 | 含义 |
| --- | --- | --- |
| `--config` | 无 | JSON 或 YAML 配置文件路径。命令行参数优先于配置文件。 |
| `--output-dir` | 当前工作目录 | 输出产物根目录。 |
| `--max-pages` | `10` | 登录后最多探索多少个页面或 SPA 内容页。对于左侧菜单切路由的后台系统，它限制最多发现多少个菜单内容页，不只是 URL 数量。 |
| `--max-contexts-per-page` | `5` | 每个页面最多探索多少个安全交互上下文，例如弹窗、抽屉、tab、popover、折叠面板。设为 `0` 表示关闭上下文探索。 |
| `--allow-destructive-actions` | `false` | 是否允许生成并执行删除、审批、支付、发布等高风险动作。探索阶段仍不会主动点击高风险按钮。 |
| `--run-id` | 自动生成 | 本次执行的唯一标识，用于输出目录和产物命名。 |
| `--agent-assist` | 默认开启 | 显式开启 Agent Assist。 |
| `--no-agent-assist` | 无 | 显式关闭 Agent Assist，回退到规则路径和 LLM 低置信度补强链路。 |
| `--agent-provider` | `browser-use` | Agent provider 名称，可选 `browser-use`、`browser-use-local`、`custom`、`private-llm`。 |
| `--agent-endpoint` | 无 | 内网 Browser-use Agent Assist 服务地址。 |
| `--agent-model` | 无 | Browser-use 背后的私有化模型名称。 |
| `--agent-readonly` | `true` | 强制 Agent Assist 只读观察模式。 |
| `--agent-timeout-ms` | `30000` | 单次 Agent Assist 调用超时时间。 |
| `--agent-local-command` | 无 | 本地 bridge 解释器或可执行文件路径，例如 `./agent/.venv/Scripts/python.exe`。 |
| `--agent-local-script` | 无 | 本地 bridge 脚本路径，例如 `./agent/browser_use_bridge.py`。 |
| `--agent-local-session-mode` | `snapshot-only` | 本地 bridge 会话模式，可选 `snapshot-only` 或 `storage-state`。 |
| `--agent-local-storage-state` | 无 | `storage-state` 模式下复用的 Playwright 登录态文件。 |

配置文件专用参数：

| 参数 | 默认值 | 含义 |
| --- | --- | --- |
| `browser.ignoreHTTPSErrors` | `true` | 探索、登录态创建和实际 Playwright 执行阶段默认忽略 HTTPS 证书错误，适配内网自签或过期证书环境；需要严格校验证书时显式设为 `false`。 |

## 配置文件

YAML 示例：

```yaml
inputPath: ./cases.xlsx
baseUrl: http://127.0.0.1:3000/login
username: tester
password: secret
outputDir: ./artifacts
maxPages: 5
maxContextsPerPage: 5
runId: demo-run

browser:
  ignoreHTTPSErrors: true

execution:
  allowDestructiveActions: false

agentAssist:
  enabled: true
  provider: browser-use
  endpoint: http://browser-use.internal.local/agent-assist
  model: internal-agent-model
  readonly: true
  timeoutMs: 30000

llm:
  enabled: true
  provider: minimax
  model: MiniMax-M1
  apiKeyEnv: MINIMAX_API_KEY
  baseUrlEnv: MINIMAX_BASE_URL
  temperature: 0
  maxTokens: 2000
  timeoutMs: 30000
```

本地 bridge 示例：

```yaml
agentAssist:
  enabled: true
  provider: browser-use-local
  model: internal-agent-model
  readonly: true
  timeoutMs: 30000
  localBridge:
    command: ./agent/.venv/Scripts/python.exe
    scriptPath: ./agent/browser_use_bridge.py
    sessionMode: snapshot-only
    maxStdoutBytes: 1048576
    maxStderrBytes: 65536
```

关闭 LLM：

```yaml
llm:
  enabled: false
```

关闭 Agent Assist：

```yaml
agentAssist:
  enabled: false
```

配置文件中的相对路径会按配置文件所在目录解析。

## Excel 格式要求

Excel 文件不强制要求固定工作表名称。未指定 sheet 时，程序优先读取 `原始用例`；如果不存在，则兜底读取第一个工作表，并在预检报告里记录实际使用的 sheet。

推荐最小列：

| 用例 ID | 模块 | 用例标题 | 输入 | 期望输出 | 原始自然语言描述 |
| --- | --- | --- | --- | --- | --- |
| TC-001 | 用户查询 | 手机号查询用户 | 手机号 13800000000 | 用户信息 | 输入手机号 13800000000，点击查询，查看得到用户信息 |

支持的列名别名：

| 业务字段 | 支持列名 |
| --- | --- |
| 用例 ID | `用例 ID`、`用例ID`、`Case ID`、`ID` |
| 模块 | `模块`、`业务模块` |
| 标题 | `用例标题`、`标题`、`名称` |
| 前置条件 | `前置条件` |
| 输入 | `输入`、`测试输入`、`数据` |
| 期望输出 | `期望输出`、`预期结果`、`期望结果` |
| 自然语言描述 | `原始自然语言描述`、`描述`、`步骤`、`操作步骤` |
| 优先级 | `优先级`、`Priority` |

字段要求：

1. `用例 ID` 建议填写；不填写时会生成 `CASE-0001` 这类编号。
2. `原始自然语言描述` 强烈建议填写，这是识别输入字段、触发动作、期望结果和 CRUD 动作的主要来源。
3. 没有描述时，程序会尝试用 `输入 + 期望输出` 拼接成描述，但识别置信度会下降。
4. 不需要在 Excel 中预先填写页面 URL、按钮 locator、元素 selector 或 iframe 信息。

按钮文字匹配会忽略前后空格、中间空格和连续空格，例如“保 存”“保  存”“ 保存 ”都会按“保存”处理。

## 探索能力

当前已支持：

1. 登录后页面探索。
2. 左侧菜单驱动的后台 SPA 内容页识别，即 URL 不变但主内容变化的场景。
3. 多层 iframe 递归识别，并在生成脚本时使用链式 `frameLocator(...)`。
4. iframe 内容区内的左侧筛选、顶部关键字检索、工具栏、原生表格、组件表格和 div/list 重复结构识别。
5. 表格头、样例行、稳定行文本、行内修改、删除、查看按钮的结构化建模。
6. 安全交互上下文探索，包括 tab、弹窗、抽屉、popover、折叠面板。
7. 弹窗/抽屉打开后生成 `context-container` 区域，并记录上下文内保存、取消等动作。
8. 上下文内元素采集，并在生成脚本时先打开上下文，再在上下文 scope 内输入、点击和断言。

探索阶段只会点击低风险上下文触发器，例如“高级搜索”“查看详情”“更多筛选”“展开条件”“订单明细”。探索阶段不会主动点击“保存”“删除”“提交”“确定”等可能产生副作用的按钮。

## 结构化语义地图

工具会把页面探索结果组织成可审计的业务语义地图：

| 对象 | 含义 |
| --- | --- |
| `PageMap` | 页面或 SPA 内容页，包含标题、菜单路径、内容摘要和主业务 iframe 标记。 |
| `FrameMap` | iframe 层级，包含 `framePathIds`、`locatorChain` 和 `semanticRole`。 |
| `RegionMap` | 页面区域，例如左侧筛选区、顶部搜索表单、工具栏、数据表格、分页、弹窗容器。 |
| `FilterMap` | 筛选控件，例如关键字输入框、下拉框、树形筛选、tab 筛选。 |
| `DataGridMap` | 表格或列表区域，例如原生表格、组件表格、虚拟表格、div/list。 |
| `GridColumnMap` | 表格列头。 |
| `GridRowMap` | 表格样例行和稳定行文本。 |
| `RowActionMap` | 行级操作，例如查看、修改、删除、更多。 |
| `ContextMap` | 交互上下文，例如弹窗、抽屉、tab、popover。 |

`PageMap.primaryFrameId` 用于标记主要业务 iframe。多层 iframe 会保留完整 `framePathIds`，用于后续匹配和 Playwright 作用域生成。

## CRUD 支持与安全边界

工具支持从 Excel 用例描述中识别基础业务动作：

| 动作 | 常见关键词 |
| --- | --- |
| 新增 | `新增`、`添加`、`新建`、`create`、`add` |
| 修改 | `修改`、`编辑`、`更新`、`update`、`edit` |
| 保存 | `保存`、`save` |
| 删除 | `删除`、`移除`、`delete`、`remove` |
| 查询 | `查询`、`搜索`、`search`、`query` |
| 查看 | `查看`、`详情`、`view`、`detail` |

安全模型分两层：

1. 探索阶段永远不主动点击高风险或写操作按钮，即使配置了 `--allow-destructive-actions`。
2. 执行阶段只根据 Excel 明确描述的业务动作生成脚本。删除、审批、支付、发布等高风险动作默认进入复核队列，只有设置 `--allow-destructive-actions` 后才允许生成并执行。

日常新增、保存、修改等基础操作可以生成脚本；删除类用例默认需要显式开启高风险执行开关。

## 登录态复用

业务系统要求登录后才能访问页面时，执行阶段默认使用统一登录态复用，而不是每条用例重复登录。

执行流程：

1. runner 在本次执行开始前使用 `--base-url`、`--username`、`--password` 登录一次。
2. 登录成功后保存 Playwright `storageState` 到 `runs/<run-id>/storageState.json`。
3. 每个生成的 Playwright 脚本通过 `AUTH_STORAGE_STATE` 环境变量复用该登录态。
4. 脚本直接打开探索阶段匹配到的业务页 URL，执行输入、点击和断言。

这个设计把登录逻辑集中在 runner 侧，便于后续维护验证码、SSO、租户选择、多账号等复杂登录场景，也避免大量用例重复登录导致耗时增加或触发风控。

## Browser-use Agent Assist

工具默认启用 `agentAssist.enabled: true`，并使用 `browser-use` 作为探索阶段辅助层。Browser-use 不替代 Playwright；Playwright 仍负责登录、页面探索、脚本生成和确定性执行。Browser-use 只接收脱敏后的页面观察数据，以 readonly 模式返回结构化候选元素、候选上下文、候选 locator、置信度、风险等级和判断理由。

如果不希望单独部署常驻 Browser-use 服务端，可以配置 `provider: browser-use-local` 使用本地子进程 bridge。CLI 会按需启动 `agent/browser_use_bridge.py`，通过 stdin/stdout 交换结构化 JSON。bridge 失败时主流程会记录 failed decision，并回退到规则路径。

`browser-use-local` 默认使用 `snapshot-only` 模式。登录仍由 Playwright 主流程完成，探索、匹配和执行恢复阶段把已采集的页面观察快照交给本地 bridge 分析，因此不会每个用例重复登录。

默认使用场景：

1. 页面结构不标准，规则探索找不到按钮或字段。
2. 多个同名按钮、同名字段或相似表格列需要结合上下文判断。
3. 弹窗、抽屉、popover、tab 没有标准 role 或稳定 class。
4. selector 失效后，需要根据页面可见内容寻找低风险替代 locator。
5. 用例描述偏自然语言，规则匹配置信度较低。

安全边界：

1. 删除、审批、支付、发布、导入、覆盖、禁用、作废、退款等动作默认不自动执行 Agent 恢复。
2. 高风险候选只进入报告和工作簿的人工复核信息，不自动合并为可执行动作。
3. Agent Assist 调用失败不会中断规则路径。
4. Agent Assist 的关键决策会写入 `report.json`、`review.html` 和自动化工作簿，便于审计。

## LLM 行为

当 `llm.enabled: true` 时，默认提供方是 MiniMax。

LLM 使用边界：

1. 规则优先，模型只做低置信度补强。
2. 模型输出必须是结构化 JSON，并带置信度。
3. 模型不可用、超时或输出无效时，会回退到规则链路。
4. 完全离线运行时建议关闭 LLM，或配置私有化模型 endpoint。

## 输出产物

假设 `--output-dir /tmp/demo --run-id demo-run`，主要产物为：

| 路径 | 含义 |
| --- | --- |
| `generated/maps/demo-run-automation.xlsx` | 自动化工作簿，包含原始用例、解析结果、页面地图、上下文地图、语义地图和复核队列。 |
| `generated/tests/demo-run/*.spec.ts` | 生成的 Playwright 测试脚本。 |
| `runs/demo-run/preflight.json` | 预检结果，包含输入、配置、浏览器证书策略、Agent/LLM 配置等检查项。 |
| `runs/demo-run/report.json` | 机器可读运行摘要，包含 LLM、Agent Assist、Agent 审计、语义地图、业务语义、预检、执行统计和失败诊断。 |
| `runs/demo-run/review.html` | 人工审查 HTML 报告，汇总页面语义对象、语义资产 diff、Agent 审计和失败/复核证据。 |
| `runs/demo-run/defects.xlsx` | 缺陷工作簿。 |
| `runs/demo-run/storageState.json` | 登录态文件。 |
| `runs/demo-run/**/trace.zip` | 失败用例 trace。 |
| `runs/demo-run/**/*.png` | 失败截图。 |

`review.html` 是给人工审查使用的可读报告；`report.json` 是给自动化流水线和后续分析使用的结构化报告。两者都记录 Agent 审计信息，便于判断哪些候选被自动接受、哪些需要人工复核、哪些被拒绝。

## 语义资产与增量探索

语义资产用于保存历史探索得到的页面语义对象，包括字段、按钮、筛选条件、表格、行级操作和上下文信息。开启后，工具会为每个页面生成稳定 fingerprint，比较旧资产和本次探索结果，并把新增、删除、变更或低置信度对象写入 `report.json` 和 `review.html` 供人工复核。

配置示例：

```json
{
  "semanticAssets": {
    "enabled": true,
    "dir": ".semantic-assets",
    "reuseMode": "safe",
    "saveAfterRun": true,
    "requireManualReviewOnDiff": true
  }
}
```

`reuseMode` 支持 `off`、`safe`、`aggressive`。`safe` 只在 fingerprint 未变或没有复核风险时复用；`aggressive` 会在没有复核对象时允许更积极复用；`off` 会关闭复用判断但仍可按配置保存本次资产。

## 预检

CLI 在导入 Excel 用例前会检查输入文件、工作表、配置、输出目录、Agent/LLM 配置、本地 bridge 配置和浏览器证书策略。阻塞性问题会 fail fast，并写入 `runs/<run-id>/preflight.json`、`runs/<run-id>/report.json` 和 `runs/<run-id>/review.html`。

浏览器证书策略默认是 `browser.ignoreHTTPSErrors: true`，会同时作用于探索阶段、登录态 `storageState` 创建阶段和生成脚本的实际执行阶段，避免内网 HTTPS 自签证书导致流程中断。显式配置为 `false` 时，预检会给出 warning，后续浏览器行为会按严格证书校验执行。

## 开发验证

```bash
npm run typecheck
npm run test:run
```

在 Windows 环境如果全量测试存在浏览器并发问题，可以使用单 worker：

```bash
npx vitest run --exclude ".claude/**" --testTimeout 180000 --minWorkers=1 --maxWorkers=1
```