Newshot

Show HN:Qpilot —— 在 Chrome 中运行纯文本手动测试用例的 AI 代理

Translation(model translation, not the source's own text)

qpilot

粘贴一条手工测试用例。AI agent 会在真实的 Chrome 中运行它,并告诉你哪一步坏了——附带证据。

npm
npm
stars
stars
一条测试用例被粘贴进来,agent 在 Chrome 中运行五个步骤,三步通过、两步失败,并给出预期结果、实际结果和截图
一条测试用例被粘贴进来,agent 在 Chrome 中运行五个步骤,三步通过、两步失败,并给出预期结果、实际结果和截图

这是一次真实运行,不是演示动画:针对 saucedemo.com 及其故意带有 bug 的 problem_user,耗时 17 秒。录像中段被加速到 1.5×。

安装就这么多。没有测试代码,没有选择器,没有配置文件。

需要:Node.js 20.12+、Google Chrome,以及一个 Anthropic API key —— 或任何兼容 OpenAI 的 endpoint(Qwen、vLLM、Ollama、企业网关)。

你会得到什么

不是「测试失败了」,而是哪一步、预期是什么、页面实际显示了什么,以及那一刻的截图:

第 4 步失败:预期购物车角标显示 2,实际——角标仍显示 1,按钮仍写着 Add to cart;下方是页面截图
第 4 步失败:预期购物车角标显示 2,实际——角标仍显示 1,按钮仍写着 Add to cart;下方是页面截图

每一步的结果都是 pass、fail 或 warn。运行结束后,Copy report 给你可以贴进工单的 Markdown,Download report 给你一个内含截图的 HTML 文件。

为什么一个绿色的步骤值得信任

让 agent 点着走完一个页面是简单的部分。难的是得到一个你无需亲自复核的 pass。qpilot 的大部分工作都在这里:

  • 预期结果来自你的测试用例。报告把它放在页面实际显示的内容旁边,标准被悄悄降低一眼就能看出来。
  • 每个 pass 都会被二次核查。一次独立的模型调用,带着干净的上下文,拿到该步骤、agent 的断言以及浏览器实际返回的内容。它只能提出异议:该步骤随后变成带原因和截图的 warn,由你来判断。
  • 尺寸和颜色是测量出来的,不是目测的。仅凭截图,某个模型把两个按钮 46 px 的重叠称为「没有重叠」。所以位置、尺寸、重叠和颜色都从浏览器读取,以像素和 RGB 表示。
  • 页面坏了,整次运行就判为失败。agent 不会靠重试绕过 bug,也不会换别的路径直到某次通过。

二次核查目前的效果,基于一个模型和一个小样本:在 45 个正确的 pass 上,它没有提出任何误报;在 13 个记录事实被故意篡改的 pass 中,它标记出了 12 个。

工作原理

  • 粘贴一条纯文本测试用例——PM 在 Confluence 里写的那种乱糟糟的也没问题。
  • agent 打开 Chrome 并执行每一步。每次操作时它都把页面读取为无障碍树,因此不存储任何会在改版后过期的信息。
  • 结果逐步实时流出。
  • 遇到 OTP 或验证码?它会暂停询问你,然后继续。

如果模型能看图片,当文字不够用时 agent 也会看页面:一个没有标签的图标、一张图片、一个图表、一个 canvas。无需开启任何开关——运行开始时 agent 会检查模型是否能读图,而对于纯文本模型,它在没有截图的情况下也能工作。

手工测试脚本化 e2eqpilot
新增一个测试写出步骤编写并维护代码写出步骤
谁能写任何人会写代码的人任何人
改版之后由人调整更新测试代码无需更新
OTP / 验证码由人处理通常会卡住运行暂停并询问你
输出你自己看着pass/fail每步 pass/fail/warn + 证据
  • 面向开发者的浏览器 agent(Playwright MCP、browser-use 之类)把一个浏览器交给 AI 助手,从 IDE 或聊天窗口里操作。qpilot 面向的是拥有测试用例的人:粘贴用例,得到每一步带证据的判定、每次失败的截图,以及一份可以附进工单的报告。不需要 IDE,不需要写 prompt。
  • 诸如 Google 的 Artemis 这类设备代理可以自动化 Android 手机。qpilot 则在桌面 Chrome 中测试 Web 应用。
  • 这里针对测试特有的能力包括:请求 mock 与请求日志、对每个通过步骤的二次校验、测量尺寸和颜色而不是“看起来没问题”、运行中途把 OTP 和验证码交给人工处理。

编写测试用例

这就是上面录屏中的用例,按原样粘贴:


        TC-014 — Add two items to the cart
URL: https://www.saucedemo.com/
Credentials: problem_user / secret_sauce

1. Open the page.
   Expected: login form with Username and Password.
2. Log in.
   Expected: Products page with 6 items.
3. Add "Sauce Labs Backpack" to the cart.
   Expected: cart badge shows 1.
4. Add "Sauce Labs Fleece Jacket" to the cart.
   Expected: cart badge shows 2.
5. Open the cart.
   Expected: both items are listed.
      

不需要特定格式——标题、编号和 “Expected:” 行都是可选的。预期结果写得越清楚,检查就越严格。一次粘贴多个测试用例,代理会按顺序运行它们,并在界面中分组显示。

更多示例和技巧:docs/test-case-format.md。

它还能做什么


        3. Replace the response of GET /api/cart with an empty list and open the cart.
   Expected: the "Your cart is empty" placeholder is shown.
4. Make POST /api/orders return 500 and click "Place order".
   Expected: an error message is shown.
5. Place the order for real.
   Expected: POST /api/orders was sent with amount=3980 and returned 201.
      

代理可以用编造的数据响应请求(如果你不提供数据,它会自己编一个像样的响应体)、修改真实响应中的某个字段、让请求失败或延迟、断网,以及读取页面实际发送和接收的内容。JavaScript 控制台错误会记录在发生该错误的步骤上。

请求和响应体中的 token、密码和 cookie 在模型或报告看到之前会被掩码处理。

运行前点击 Attach files,代理就可以把文件交给页面上的任意上传控件——包括样式化的“Choose file”按钮背后隐藏的 <input type=file>。

文件只在运行期间存在,运行结束即被删除。代理可以上传它们,但永远看不到其中的内容。

  • 打开新标签页的链接会把代理切换到该标签页;它也能切回来。
  • 原生 alert / confirm / prompt 对话框默认会被接受。在步骤中写“press Cancel”,代理就会改为关闭对话框。
  • 在 password 字段中输入的任何内容都会在日志和报告中掩码显示。

Choose folder 让 qpilot 指向一个存放 .md 文件的目录。勾选你要运行的用例并作为批次运行——一个接一个,带有实时状态和计时,以及一个 Stop 按钮。运行完成的记录会出现在 Recent runs 下。

运行结束后,你可以 Run again,或者 Edit test case 后重新运行。浏览器可见性按每次运行设置:Run 保持无头模式,Run with preview 让你观看 Chrome 的工作过程。

模型

打开 Settings(首页右上角)选择提供商、粘贴 API key 并输入模型 id。更改会应用到下一次运行——无需重启。首次启动时 qpilot 会自行打开 Settings;npx qpilot config 可直接打开同一页面。

  • Anthropic (Claude) —— 粘贴你的 sk-ant-… key。默认使用 claude-haiku-4-5。base URL 是可选的,用于通过企业代理访问 Claude。
  • Custom —— 任何兼容 OpenAI 的端点。提供 base URL、token 和模型 id:Base URL: https://dashscope-intl.aliyuncs.com/compatible-mode/v1 Model id: qwen2.5-72b-instruct 该模型必须支持 tool calling——代理正是通过它来驱动浏览器。

Custom —— 任何兼容 OpenAI 的端点。提供 base URL、token 和模型 id:


        Base URL: https://dashscope-intl.aliyuncs.com/compatible-mode/v1
Model id: qwen2.5-72b-instruct
      

该模型必须支持 tool calling——代理正是通过它来驱动浏览器。

像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复中和在 tool call 中都请完全按原样使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。

你的选择会保存到 ~/.qpilot/config.json(权限 600)。使用 Anthropic 提供商时,可以通过 ANTHROPIC_API_KEY 环境变量或 .env.local 文件完全跳过设置步骤。

须知

  • 一切都在本地运行。除了模型调用之外,没有任何数据离开你的机器,因此 qpilot 可用于 staging 和内部网络。
  • 速度取决于模型的速度:一次运行大部分时间都在等待模型的回答。运行页面会显示时间分布(模型 / 浏览器 / 调用次数)。输出快且支持 tool calling 的模型能让运行时间缩短数倍。
  • 本地 API 只响应 qpilot 自己的页面:来自其他网站的请求会被拒绝,localhost / 127.0.0.1 之外的主机名同样会被拒绝。如果要在别的名称下提供 qpilot(例如放在反向代理后面)?把它列入 QPILOT_ALLOWED_HOSTS。
  • 运行记录保存在内存中,只保留最近 50 次——重启服务器即清空。
  • 浅色和深色主题:默认跟随系统,也可以在 Settings 中选择。

贡献

欢迎提交 issue 和 pull request——见 CONTRIBUTING.md。问题讨论请到 Discussions;安全相关问题见 SECURITY.md。

使用 Claude 和 Playwright 构建。如果 qpilot 帮你节省了时间,在 GitHub 上点一个 ⭐ 带来的帮助比你想象的更大。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗