qpilot：用 AI Agent 在真实浏览器中跑手动测试用例

qpilot 是一款把「手动 QA 测试用例」直接交给 AI Agent 在真实浏览器中执行的工具。用户只需粘贴自然语言描述的测试步骤，工具就会调用 LLM 驱动 Chrome 完成点击、输入、上传等操作，并逐条返回通过、失败或告警的结果。安装方式为 npx qpilot，首次启动会在浏览器中引导用户选择模型并打开操作界面。

运行机制

qpilot 的工作流程围绕「无代码、无选择器、无配置文件」展开：

• 输入：用户粘贴一份纯文本测试用例，格式自由，PM 在 Confluence 中写的那种「口语化步骤」即可。
• 执行：Agent 在 Chrome 中按照步骤依次操作，每一步都基于页面的可访问性树（accessibility tree）进行判断，避免依赖易失效的 DOM 选择器。
• 输出：每一步实时返回 pass / fail / warn，并附上页面证据文案；失败时自动截图。
• 异常处理：遇到 OTP 验证码或人机验证时，Agent 会暂停并请求人工介入，处理后继续。

工具支持文件附件，可在运行前上传头像、CSV、PDF 等，由 Agent 交给页面上对应的 <input type="file"> 控件，文件在运行结束后即删除，Agent 本身不读取其内容。

模型与配置

qpilot 支持两类模型后端：

• Anthropic（Claude）：粘贴 sk-ant-… 格式的 API Key 即可，默认使用 claude-haiku-4-5，也支持通过 base URL 走企业代理。
• 自定义 OpenAI 兼容端点：填写 base URL、token 和模型 ID 即可接入，例如通过阿里云 DashScope 接入 qwen2.5-72b-instruct，或对接 vLLM、Ollama、企业内网网关等自托管模型。

Agent 通过 tool calling 驱动浏览器，因此所选模型必须支持工具调用。配置写入 ~/.qpilot/config.json（权限 600），也可通过 ANTHROPIC_API_KEY 环境变量或 .env.local 文件跳过交互式配置。

批量与本地化

对于积累了大量 markdown 格式测试用例的团队，qpilot 提供「选择文件夹」入口，可一次勾选多个 .md 文件按顺序批量执行，UI 中实时显示状态、用时，并提供「Stop」中断按钮，完成的运行结果会留在「Recent runs」中。所有运行只在内存中保留最近 50 条，重启服务后清空。

需要强调的是，模型调用之外的一切——浏览器、文件、测试结果——都运行在本地，因此可以对接 staging 环境和仅内网可访问的系统。运行模式方面，Run 默认无头执行，Run with preview 则会打开 Chrome 窗口供用户观看 Agent 实时操作。

适用场景与局限

qpilot 的定位介于「纯手工测试」与「脚本化端到端测试」之间：

• 谁来写用例：任何人都可以写，只要把步骤和期望结果说清楚。
• 改版之后：由人手动适配，Agent 在下次运行中重新学习新页面。
• OTP / 验证码：交给人工处理，运行不被打断。
• 输出形式：每一步给出 pass / fail / warn 及证据截图，比「看一遍回放」更易审阅。

工具基于 Claude 和 Playwright 构建，本质上是把 Playwright 的浏览器控制能力包成 LLM 可调用的工具。需要注意的是，如果页面本身存在严重故障导致 Agent 无法操作，运行仍会判定为失败——这并非缺陷，而是设计上的预期行为。