Qpilot 实战教程：粘贴测试用例，AI Agent 自动在真实浏览器中执行

手工测试太慢，自动化测试又得写脚本维护——这是每个开发者都熟悉的困境。手动测试全靠人盯着屏幕逐条验证，枯燥且容易漏检；Selenium 和 Playwright 脚本虽然能跑，但每次 UI 改动就要修选择器，维护成本不低。

Qpilot 给出了第三条路：直接把自然语言写的测试用例丢给 AI Agent，它在真实浏览器里帮你逐条执行，实时显示 pass/fail/warn 结果。 不需要写任何代码，不需要维护测试框架，测试用例就是纯文本步骤描述。

Qpilot 是什么

Qpilot 是一个 MIT 许可证的开源 TypeScript CLI 工具（当前版本 0.7.3），核心能力只有一句话：读取你用自然语言写的测试用例，在 Chrome 中按步骤执行并报告结果。

它的工作流程极其简单：

1. 你粘贴一个纯文本测试用例（包含 URL、步骤、预期结果）
2. Qpilot 打开 Chrome，按步骤操作页面
3. 每个步骤实时显示 pass（通过）、fail（失败）或 warn（警告）
4. 遇到验证码或 OTP 时暂停，在你手动处理后继续执行

整个过程不需要写一行 Selenium 或 Playwright 脚本，不需要配置任何测试框架。

对比传统方案

快速上手

安装与启动

Qpilot 依赖 Node.js 20.12+、Google Chrome 和 Anthropic API Key（或其他 OpenAI 兼容的模型端点）。

npx qpilot

首次运行会通过箭头键菜单引导你完成 Provider 设置：

• Anthropic（Claude）：输入 sk-ant-… 格式的 API Key，默认模型是 claude-haiku-4-5
• 自定义端点：任何兼容 OpenAI 接口的模型，如 Qwen、vLLM、Ollama 或企业网关。提供 base URL、API Token 和 model id 即可

设置完成后，浏览器自动打开 http://localhost:3847，进入 Qpilot 界面。

配置信息保存在 ~/.qpilot/config.json（权限 600），密钥不会泄露。

配置快捷方式

你可以在当前目录创建 .env.local 文件免去交互式设置：

echo "ANTHROPIC_API_KEY=sk-ant-***" > .env.local

然后通过 npx qpilot config 随时重新设置 Provider。

实战：编写并执行测试用例

第一个测试用例

Qpilot 的测试用例用纯文本格式编写，包含 URL、前置条件和按编号排列的步骤。以下是一个针对 SauceDemo 的登录测试：

TC-001 — Login and add item to cart
URL: https://www.saucedemo.com/
Credentials: standard_user / secret_sauce

Steps:
1. Open the home page.
   Expected: login form with Username and Password fields is visible.

2. Enter credentials and click Login.
   Expected: Products page opens with 6 items.

3. Click "Add to cart" on "Sauce Labs Backpack".
   Expected: cart counter shows 1.

4. Click the cart icon.
   Expected: cart contains Sauce Labs Backpack at $29.99.

粘贴这个用例到 Qpilot 界面，点击运行，Agent 会依次执行每一步并实时更新状态。

批量运行测试文件

如果你的测试用例保存在 .md 文件中，可以直接让 Qpilot 读取整个目录：

• 点击 Choose folder 选择包含 .md 文件的目录
• 勾选需要运行的用例
• 点击 Run 批量执行

每个文件依次运行，实时显示状态和耗时。中途可以点击 Stop 停止当前批次。完成的运行（包括历史批次）会在首页的 Recent runs 中展示。

这种模式尤其适合回归测试场景——你只需要维护一批 .md 测试用例文件，每次改版后在 Qpilot 中批量运行一遍即可。

编写测试用例的最佳实践

从实战经验来看，写好 Qpilot 测试用例需要注意几点：

1. URL 必须明确：每个用例第一行写清楚目标 URL，避免 Agent 猜错页面
2. 预期结果尽量具体：不只是”页面正常”，而是”登录表单可见”、”购物车显示 1 件商品”这样可验证的描述
3. 步骤粒度适中：一个步骤做一个操作 + 一个验证，不要在一个步骤里做”填写表单并点击提交并验证跳转”
4. 前置条件先写清：需要登录的页面，在用例顶部标注凭据或前置操作

模型选择建议

Qpilot 支持两种 Provider 模式：

• Anthropic Claude（默认 claude-haiku-4-5）：开箱即用，Haiku 模型在浏览器操作任务上性价比极高
• 自定义 OpenAI 兼容端点：如果你有自己的本地模型（如通过 Ollama 或 vLLM 部署 Qwen），只需要模型支持 function/tool calling 即可

在企业环境中，你可以把 Qpilot 指向公司内部的 AI 网关或代理，无需把 API Key 暴露到公网。

适用场景

Qpilot 最适合这几类场景：

• 快速验证 Bug 修复：修完 Bug 后写一个简单的自然语言用例，让 Agent 自动验证修复效果
• 回归测试：把核心流程写成 .md 文件，每次发布前批量跑一遍
• 跨团队测试协作：产品经理或 QA 可以直接写自然语言用例，无需开发人员介入编写自动化脚本
• 第三方网站集成测试：不需要维护 DOM 选择器，Qpilot 通过 ARIA 语义理解页面结构，UI 变化不影响用例执行

局限与注意事项

• Qpilot 依赖 Anthropic 或其他 LLM 的 API，执行速度和准确性受模型能力影响
• 运行记录在内存中，最多保留最近 50 条，重启服务器后清空
• 目前仅支持 Chrome 浏览器（底层使用 Playwright）
• API Key 保存在本地 ~/.qpilot/config.json，仅发送到你选择的模型 Provider

总结

Qpilot 解决了一个很实在的问题：测试用例应该和代码写在一起，但执行测试不应该需要维护测试框架。 把用例写成 Markdown 文件放在仓库里，需要验证时让 AI Agent 替你跑一遍——这种工作流让测试回归到”描述行为”的本质，而不是”写选择器”的技术活。

对于已经使用 AI 编码 Agent 的团队，Qpilot 是一个天然互补的工具：Agent 写代码，Qpilot 测页面，两边都用自然语言交互，开发者只需要专注于什么该做、什么算对。

相关链接：

• Qpilot GitHub 仓库
• Qpilot npm 包
• Claude API
• Playwright