智能体可观测性

让 E2E 测试可调试的工件捕获层。日志、跟踪、截图。

本文档描述了 artifact-capture 层，它使桌面应用能够通过现有的 WDIO/Appium Chromium 运行环境被代码代理（Codex、Claude Code、Cursor）检查。

它的范围刻意很窄：仅包含一个规范化的引导和隐私流程，并在磁盘上保存截图、页面源码转储以及模拟后端请求日志。

简而言之

bash app/scripts/e2e-agent-review.sh

产物会落在：

app/test/e2e/artifacts/<ISO-timestamp>-agent-review/
  01-welcome.png
  01-welcome.source.xml
  02-post-welcome.png
  02-post-welcome.source.xml
  03-post-onboarding.png
  03-post-onboarding.source.xml
  04-privacy-panel.png
  04-privacy-panel.source.xml
  mock-requests-after-welcome.json
  mock-requests-after-onboarding.json
  mock-requests-after-privacy.json
  failure-<test>.png              # 仅在失败时
  failure-<test>.source.xml       # 仅在失败时
  meta.json                       # 运行元数据 + 检查点索引

脚本会在最后打印解析后的产物目录。

组成部分

部分	路径	角色
辅助程序	app/test/e2e/helpers/artifacts.ts	运行目录， captureCheckpoint, captureFailureArtifacts, saveMockRequestLog
WDIO 钩子	app/test/wdio.conf.ts (afterTest)	任何测试失败时都会始终转储截图 + 源码
规范测试	app/test/e2e/specs/agent-review.spec.ts	欢迎页 → 引导流程 → 隐私面板，并带有命名检查点
包装脚本	app/scripts/e2e-agent-review.sh	构建 + 运行 + 打印产物目录
稳定选择器	data-testid 于 OnboardingNextButton, Onboarding 遮罩层 + 跳过按钮， WelcomeStep, PrivacyPanel	对代理可靠的导航锚点

环境覆盖项

变量	效果
E2E_ARTIFACT_DIR	强制指定一个运行目录（跳过自动时间戳命名）
E2E_ARTIFACT_ROOT	自动生成运行目录的父目录（默认： app/test/e2e/artifacts)
E2E_ARTIFACT_LABEL	用于自动生成的运行目录名称中的标签（默认： 运行；包装脚本设置为 agent-review)

在新的 spec 中使用该辅助程序

import { captureCheckpoint, saveMockRequestLog } from "../helpers/artifacts";
import { getRequestLog } from "../mock-server";

await captureCheckpoint("after-connect-click");
saveMockRequestLog("after-connect-click", getRequestLog());

captureCheckpoint 使用数字编号的捕获，因此运行目录按时间顺序排列。 captureFailureArtifacts 已接入 wdio.conf.ts 并会在任何失败的测试中自动触发，因此 spec 不应直接调用它。

有意不在范围内的内容

• 跨每一种组件状态的视觉基线 / 图片差异比对。

• 每次点击都捕获截图（噪音太大）。

• 实时集成（Gmail、Notion、Telegram）；仅使用模拟服务器。

• 新的测试框架 / 报告器。

只有在这一轮流程验证通过后，才扩展到更多流程。