bug0inc/qa-agent

Bug0 AI – AI 驱动的 Playwright 回归测试

它是什么 – 一个开源的 TypeScript 库，让您能以自然语言编写 Playwright 浏览器测试。该库将每个步骤发送给 LLM（Claude、Gemini、OpenAI 的 computer-use agent 等），获取操作指令，在浏览器中执行它们，并使用多模型共识引擎验证结果。它还会将成功的步骤缓存到 Redis 中，使后续的执行既快速又便宜。

主要功能

功能	运作方式
自然语言步骤	runSteps() 接收一个 {description, data?, waitUntil?, ai?} 对象数组。描述为纯英文（例如 “Click Acme Circles T-Shirt”）。该库会格式化提示词，调用配置好的 LLM，并将模型的响应转换为 Playwright 操作。
多模型断言引擎	对于每个 assertion，该库会并行调用 Claude 和 Gemini。如果它们意见不一致，则由第三个“仲裁”模型（可配置）决定，或者您可以选择立即失败 (fail-on-disagreement)。
智能缓存	成功的步骤执行会存储在 Redis 中，键值为 userFlow + step.description。当缓存命中时，步骤会直接重播而无需调用 LLM，大幅降低延迟与成本。
自动修复	当缓存的步骤失败时，该库会退回到 LLM 重新计算操作，然后更新缓存。
视频断言	在断言上设置可选的 video: true 会记录整个步骤执行过程，将 .webm 上传到 Gemini 的 Files API，并让 Gemini 根据视频评估断言（适用于像提示信息这类短暂的 UI）。
AI 网关支持	您可以通过 Vercel AI Gateway、OpenRouter、Cloudflare AI Gateway 路由所有 LLM 调用，或直接与提供者（Anthropic、Google、OpenAI）通讯。
CUA 模式	当选择 mode: "cua" 时，该库会使用 OpenAI 的 computer-use agent (gpt-5.5 + 内置 computer 工具) 进行可视化、基于屏幕截图的自动化。
动态占位符	{{run.*}}、{{global.*}}、{{data.*}} 和 {{email.*}} 让您能将随机电子邮件、ID 或从收到的邮件中提取的值注入到步骤中。
遥测与日志	可选的 OpenTelemetry 追踪 (Axiom) 和结构化的 Pino 日志。
电子邮件提取	内置 emailsink 提供者（抛弃式收件箱）或自定义提供者以获取验证码等。

典型工作流程

1. 建立 Playwright 项目 – npm init playwright@latest bug0-ai-project (选择 TypeScript)。
2. 安装库 – npm install @bug0/ai dotenv。
3. 新增您的 LLM 凭证 – 至少一个 Anthropic 密钥和一个 Google Generative AI 密钥（或使用网关）。将它们放入 .env 文件中。
4. 一次性配置 – 在测试套件顶部调用 configure({ ai: { gateway: "vercel", models: { … } }, redis: { url }, telemetry: { … } })。
5. 编写测试 – 使用 runSteps({ page, userFlow, steps, assertions, test, expect })。每个步骤都是纯英文描述；断言也是自然语言字符串。
6. 执行 – npx playwright test example.spec.ts --project chromium。报告中包含 AI 生成的摘要。

测试示例 (TypeScript)

import { test, expect } from "@playwright/test";
import { runSteps, configure } from "@bug0/ai";

configure({
  ai: { gateway: "vercel" },
});

test("Shopping cart", async ({ page }) => {
  await runSteps({
    page,
    userFlow: "Add product to cart",
    steps: [
      { description: "Navigate to https://demo.vercel.store" },
      { description: "Click Acme Circles T-Shirt" },
      { description: "Select color", data: { value: "White" } },
      { description: "Add to cart", waitUntil: "My Cart is visible" },
    ],
    assertions: [{ assertion: "You can see My Cart with Acme Circles T-Shirt" }],
    test,
    expect,
  });
});

配置重点

• 模型插槽 – 八个插槽（步骤执行、用户流程低/高、主要/次要/仲裁断言、工具、CUA）。默认值为 Gemini-flash（用于低成本步骤）和 Claude-4.5-haiku（用于主要断言）。
• Redis – 设置 REDIS_URL 或通过 configure({ redis: { url } }) 传递以启用缓存和全局占位符。
• 网关 – 根据选择的网关设置 AI_GATEWAY_API_KEY、OPENROUTER_API_KEY 等。
• CUA 模式 – 需要具有 computer 工具访问权限的 OPENAI_API_KEY；设置 mode: "cua" 和 gateway: "none"。
• 遥测 – 提供 AXIOM_TOKEN/AXIOM_DATASET 或以程序方式配置它们以获取 OpenTelemetry 追踪。

谁会使用它

• 已经使用 AI 代理（例如 Bug0 的 FactoryKit）生成 UI 代码，且需要一个能容忍频繁 DOM 变更的回归测试套件的团队。
• 希望快速编写测试而无需维护脆弱选择器的 QA 工程师。
• 希望将 LLM 驱动的自动化与传统 Playwright 可靠性功能（如缓存和视频捕获）结合的开发人员。

README 中提到的限制

• 测试套件本身仍然很小；欢迎更多边缘案例覆盖。
• 视频断言会绕过网关，需要直接的 Google API 密钥。
• CUA 模式不能与网关混合使用；它必须直接与 OpenAI 通讯。
• 多步骤缓存尚未实现（仅缓存单步骤操作）。

授权 – FSL-1.1-ALv2（一种宽松的开源授权）。

---

以上所有信息均直接取自仓库的 README；未推断出任何额外功能。