如何用Expect为每次PR加上真实浏览器验证：GitHub Actions部署与CI模式实战-创锋一号

如何用Expect为每次PR加上真实浏览器验证：GitHub Actions部署与CI模式实战

【免费下载链接】expectExpect tests your agent's code in a real browser项目地址: https://gitcode.com/gh_mirrors/expect6/expect

Expect 是一个面向 AI 编码 Agent 的真实浏览器验证工具：它读取代码变更、自动生成测试计划，并在真实浏览器里实际运行。本文带你 3 步完成GitHub Actions 部署，用 Expect 的CI 模式（--ci）让每个 Pull Request 都自动跑一遍浏览器验证——无需手写一条测试脚本。

为什么需要“真实浏览器”这一层验证

单元测试和静态检查很难发现 UI 层面的回归：按钮 hover 失效、表单提交后不跳转、页面 5xx 报错……这些只有真的打开浏览器才知道。

Expect 的思路很直接（详见 README.md 的 CI 问答）：

读 diff：分析 PR 中改动的文件，自动生成一份测试计划
跑浏览器：基于 Playwright 在真实浏览器中模拟用户操作
报结果：把发现的问题反馈给 Agent，由它修复后重新验证

在 CI 场景下，你不需要维护选择器、不需要编写断言——这正是它与传统 E2E 框架最大的区别。

一键安装步骤：生成 GitHub Actions 工作流

在你的项目根目录（不是 Expect 仓库）里执行一条命令：

npx -y expect-cli@latest add github-action

命令会做 3 件事（实现见 apps/cli/src/commands/add-github-action.ts）：

自动探测环境：识别你的包管理器（npm / pnpm / yarn / bun / deno），并探测项目的开发服务器端口
生成工作流：写出 [.github/workflows/expect.yml]，每个 PR 都会触发测试
配置密钥：如果你的终端里gh已登录，它可以通过claude setup-token一键生成 API Token 并写入仓库的ANTHROPIC_API_KEYsecret

手动补密钥也很简单：

gh secret set ANTHROPIC_API_KEY

💡 加-y参数可跳过所有交互提示，直接使用默认值（npm、http://localhost:<探测到的端口>）。

生成的工作流里有什么

生成的 expect.yml 是一个可以直接读懂的标准 workflow，关键设计：

配置项	说明
`on: pull_request: branches: [main]`	只对合入 main 的 PR 触发
`if: ... permissions.write == true`	外部 fork 提交不消耗 CI 额度、无法读取 secrets
`fetch-depth: 0`	拉取完整历史，Expect 才能读到完整的 PR diff
`EXPECT_BASE_URL`	测试目标地址，默认指向本地开发服务器
`timeout-minutes: 30`	单次执行最长 30 分钟
`permissions: pull-requests: write`	允许 Expect 在 PR 上自动评论测试结果

执行链路是：安装依赖 → 安装 Playwright 浏览器（Chromium/WebKit/Firefox）→ 启动开发服务器并等待就绪 → 运行expect-cli@latest --ci→ 上传.expect/sessions/测试产物（视频和截图）。

CI 模式实战：30 分钟内它做了什么

--ci标志（等价于在 index.tsx 中注册的add github-action触发的无头执行）会让 Expect 进入专为无人值守设计的运行方式：

Headless：不开可见浏览器窗口
跳过 Cookie 提取：不读取你本地浏览器的登录态
自动批准计划：测试计划生成后无需人工确认（-y效果）
30 分钟硬超时：超时自动判负，常量定义在 constants.ts，可用--timeout <ms>覆盖
心跳输出：每 60 秒打印一次"仍在运行"，防止 CI 日志看起来卡死
标准退出码：通过返回0，失败返回1，直接决定 PR 检查项红绿

失败时还会向 CI 输出::error注解（见 ci-reporter.ts），让错误定位到具体步骤。

结果回传：PR 评论、步骤摘要与视频产物

这是 GitHub Actions 集成最爽的部分——Expect 会在 PR 页面自动贴一条测试报告（实现见 run-test.ts）：

PR 评论：一个带 ✅/❌ 的状态表格，逐步骤列出标题、结果和耗时，并附完整输出的折叠区；重复运行时更新同一条评论，不会刷屏
Step Summary：向GITHUB_STEP_SUMMARY写入结果徽章和报告全文（见 gha-output.ts），在 Actions 页面点开步骤即可回看
产物上传：整个会话的录屏视频和失败截图保存在.expect/sessions/，随 workflow artifacts 下载

进阶配置：最快适配你的项目

测部署后的预览环境：在仓库 Variables 里设置EXPECT_BASE_URL，工作流会跳过本地开发服务器，直接测试你指定的线上/预览 URL
JSON 输出：加--output json，Expect 会输出一份结构化的CiResultOutput（状态、每步耗时、视频/截图路径），方便你自己再加工成其他报表
自定义测试意图：配合-m "重点测试登录流程"给测试计划补充自然语言指令
复用已保存的 Flow：-f <slug>可以直接复用你本地沉淀的测试流程

更多 MCP 客户端的接入方式（Claude Code、Cursor、VS Code 等）见 docs/mcp.md。

常见问题（FAQ）

Q：CI 里失败是代码问题还是 Expect 误报？先看 PR 评论里失败步骤的耗时和完整输出，再下载expect-test-results产物里的录屏视频，30 秒内就能定位。

Q：本地开发服务器启动很慢怎么办？把EXPECT_BASE_URL指向一个部署好的预览环境，工作流会自动跳过"启动开发服务器"这一步。

Q：非 GitHub 的 CI 能用吗？可以。--ci本身与平台无关，任何支持无头环境的流水线都能跑，只是自动评论 PR 等增强能力只在 GitHub Actions 生效。

Q：成本怎么控制？工作流默认只对有写权限的提交者触发（fork 提交不跑），30 分钟超时兜底，密钥存于 Secrets 不会被 fork 带走。

按上面 3 步部署完成后，你的每个 PR 都会多一道"真实浏览器"把关——Agent 写的代码，由一个真的浏览器来验收。🚀

【免费下载链接】expectExpect tests your agent's code in a real browser项目地址: https://gitcode.com/gh_mirrors/expect6/expect

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析