端到端测试
如何运行端到端测试套件:使用 Playwright 针对独立核心,使用 WDIO 通过原生 Wry 宿主,以及本地脚本、环境变量和 CI 流水线。
端到端覆盖使用 Rust mock 后端、真实浏览器中的 Playwright,以及通过桌面 Wry 主机运行的 WebDriverIO(WDIO)。每个断言都有唯一负责人:Playwright 负责浏览器渲染行为;WDIO 负责需要原生进程、窗口、操作系统或 Tauri IPC 的行为。CI 中只运行受支持的 Linux 桌面 harness。macOS 和 Windows 的桌面作业保持禁用,直到有原生驱动可用。
概览
桌面 E2E 测试使用 WebDriverIO(WDIO)通过单个 tauri-driver (WebDriver)会话,针对其原生 Wry/WebKit webview 进行驱动:
Linux
tauri-driver + WebKitWebDriver
4444
调试二进制
CSS / DOM
Linux CI 通过 Xvfb 驱动调试二进制,经由 tauri-driver。macOS 和 Windows 目前还没有自动化桌面 E2E 覆盖。它们曾使用的基于 Chromium 的驱动已经不再可用,必须由原生驱动(macOS 上的 Appium Mac2,Windows 上的 WinAppDriver)来替代。 pnpm --filter openhuman-app test:e2e:build 仍会生成一个 .app 在 macOS 上用于手动测试的 bundle,但那里没有受支持的自动化会话。
快速开始
Linux
# 构建 E2E 应用
pnpm --filter openhuman-app test:e2e:build
# 通过 tauri-driver 会话运行一个原生 spec
pnpm --filter openhuman-app test:e2e:session
# 在四个桌面套件组中运行原生专属流程
pnpm --filter openhuman-app test:e2e:all:flows
# 列出分配给第 1 车道且不启动 core 的 Playwright 单元
bash app/scripts/e2e-web-shards.sh --lane=1 --lanes=4 --list
# 运行该 Playwright 车道(每个单元都使用新的 core 和 workspace)
bash app/scripts/e2e-web-shards.sh --lane=1 --lanes=4
# 检查 spec 基名是否只有一个 runner 负责人
pnpm e2e:ownership:check
# 运行单个 spec
bash app/scripts/e2e-run-spec.sh test/e2e/specs/smoke.spec.ts smokeapp/scripts/e2e-run-session.sh 启动 tauri-driver 在 TAURI_DRIVER_PORT (默认 4444)使用 WebKitWebDriver 作为其原生驱动,等待其 /status 端点,然后针对 app/test/wdio.conf.ts运行 WDIO。 在无头 Linux 上,应用本身在 Xvfb 下运行以获得虚拟显示;驱动进程不需要显示。
macOS 上的 Docker(本地 Linux harness)
要从 macOS 运行相同的 Linux harness,请使用 Docker。
需要 Docker Desktop 或 Colima。仓库以 bind mount 方式挂载,因此构建结果会在多次运行之间保留。
架构
平台检测
app/test/e2e/helpers/platform.ts 导出两个函数,二者都被硬编码为 true: isTauriDriver() 和 supportsExecuteScript()。每个会话都暴露 webview DOM,并支持 browser.execute(),因此仍然对任一检查分支的 spec 总会走 DOM 路径。把它们当作兼容性 shim,而不是平台检测。
元素辅助函数
app/test/e2e/helpers/element-helpers.ts 在 webview DOM 之上提供一个统一 API:
waitForText(text)
对 DOM 文本内容使用 XPath
waitForButton(text)
按钮 / [role="button"] XPath
clickText(text)
标准 el.click()
clickNativeButton(text)
标准 el.click() 在按钮上
clickToggle()
[role="switch"] / input[type="checkbox"]
waitForWindowVisible()
窗口句柄检查
waitForWebView()
document.readyState 检查
hasAppChrome()
窗口句柄检查
dumpAccessibilityTree()
HTML 页面源代码
稳定的测试 ID
优先使用稳定的 data-testid 用于 UI 交互点的 hook,供 E2E spec 点击或轮询。使用如下分类法 <surface>-<element>-<id?>,例如:
cron-jobs-panel,cron-refreshcron-job-row-<jobId>,cron-job-toggle-<jobId>,cron-job-run-<jobId>,cron-job-view-runs-<jobId>,cron-job-remove-<jobId>settings-nav-<routeId>skill-row-<skillId>,skill-install-<skillId>,skill-uninstall-<skillId>thread-row-<threadId>,new-thread-button,send-message-buttononboarding-next-button
使用 waitForTestId(testId) 和 clickTestId(testId) 来自 element-helpers.ts 当 spec 针对这些 hook 之一时使用。保留文本选择器用于面向用户可见文案的断言,而不是用于行/动作发现。
深链接辅助函数
app/test/e2e/helpers/deep-link-helpers.ts 处理认证深链接:
主要路径:
browser.execute(window.__simulateDeepLink(url))。它适用于 tauri-driver 支持的每个平台上的 webview。仅限 macOS 的回退:
macos: deepLink扩展命令,然后open -a ...。CI 不会测试这些,因为 macOS 没有自动化桌面会话。Linux 没有 shell 回退。
xdg-open openhuman://...需要一个.desktop文件来注册 URL scheme,而 CI 容器中没有这个文件。如果那里 webview simulate 调用失败,triggerDeepLink会立即抛出。
对于 release candidate,如果你修改了单实例或深链接启动代码,也要在 Linux 或 macOS 上手动运行一次 secondary-instance smoke test。它会测试 tauri-plugin-single-instance,OpenHuman 将其注册为 deep-link 功能。
正常启动 OpenHuman 并保持其运行。
触发
openhuman://auth?token=e2e-token&key=auth通过操作系统打开器。确认已在运行的窗口接收到回调,而不是启动第二个应用实例。
确认辅助进程干净退出。
这可以捕获在 Tauri 的深链接转发路径安装之前就启动,或以错误退出的第二个实例。
编写跨平台 spec
使用中的辅助函数
element-helpers.ts。切勿在 spec 中直接使用原始XCUIElementType*选择器。使用
clickNativeButton(text)而不是内联按钮点击代码。使用
hasAppChrome()而不是检查XCUIElementTypeMenuBar.使用
waitForWebView()而不是检查XCUIElementTypeWebView.对于仅限 macOS 的测试,使用
process.platform守卫或单独的 spec 文件。使用
navigateViaHash(route)用于 hash 路由。返回前它会等待 hash、document.readyState以及已挂载的 React 根。完成 onboarding 后,walkOnboarding()还会等待#/home以及一个 Home 页标记,然后才允许 spec 导航到其他位置。
环境变量
TAURI_DRIVER_PORT
4444
端口 tauri-driver 监听于; wdio.conf.ts 连接到此处
E2E_MOCK_PORT
18473
模拟后端服务器端口
E2E_PORT_BASE
未设置
Web 车道端口区块:mock base, core base+1, web host base+2
OPENHUMAN_WORKSPACE
(临时目录)
应用 workspace 目录
OPENHUMAN_SERVICE_MOCK
0
启用服务 mock 模式
OPENHUMAN_E2E_MODE
未设置
启用具破坏性的测试支持 RPC;E2E 运行器会将其设置为 1
OPENHUMAN_E2E_AUTH_BYPASS
未设置
启用 JWT 绕过认证
DEBUG_E2E_DEEPLINK
(详细)
设置为 0 以静默深链接日志
E2E_FORCE_CARGO_CLEAN
未设置
在 E2E 构建前强制 cargo clean
同一台机器上的两个 web E2E 会话需要不同端口。只要某个车道的三个端口中有任何一个已在监听,该车道就会拒绝启动。它的就绪探测只是普通的 HTTP GET,而另一个会话的 mock、core 和 web host 也会同样愉快地响应,而 openhuman-core run 会回退到相邻端口而不是退出,因此它可能会在一个没有任何探测会访问的端口上保持存活。为构建和运行都设置 E2E_PORT_BASE 。mock 和 core 端口被编译进 bundle,之后无法更改。
CI 工作流
Push / PR 检查
默认的 pull request 门禁是 .github/workflows/ci-fast-hosted.yml:质量检查加上每个已变更区域的完整单元测试套件。PR 到 main.
.github/workflows/ci-full.yml 会在目标为 release 的 pull request 上以及每次 push 到该分支时运行。其最终门禁要求通过 Playwright 矩阵、原生桌面套件和 Rust E2E:
Rust mock 后端
rust-e2e
Linux
Playwright web
playwright-e2e
四个必需的 Linux 作业,每个作业 16 个普通分片,另加轮询特殊情况
桌面
e2e-desktop,通过 e2e-reusable.yml
四个 Linux 套件组
Playwright 先构建一次 web bundle 和独立 core,然后将同一个产物上传到全部四个必需车道。必需选择会运行发现的 111 个 spec 中的 110 个:整合清单中的全部 48 个活跃浏览器负责人及其断言接收者仍然是必需项,其他所有健康的浏览器 spec 也同样如此。它安排了 64 个普通分片和 9 个独立案例(Connections 别名、Connections 深链接,以及 7 个 Skills 搜索/安装案例),每个都有自己的 core 和 workspace:总计 73 个必需单元。另有一个 playwright-legacy-diagnostic 作业运行未更改的 aui-tool-result-elements.spec.ts ,作为一个文件原子单元。其组件兼容性阻塞在 issue #236中跟踪。只有这个诊断作业是建议性的;它被排除在最终门禁之外,而四个必需车道仍保持严格。调度器会继续执行已分配单元以收集失败情况,并在任何必需单元失败时以非零状态退出。因此,CI Full 会在必需和诊断作业上运行 74 个新的 Playwright 单元,但不会声称旧版诊断已通过。手动 Playwright 会严格选择全部 111 个 spec,使用相同的 64 个分片和 9 个独立案例(73 个单元);它没有建议性选择。
桌面车道调用可复用工作流,并设置 run_linux: true, run_macos: false 和 run_windows: false,因此只运行 Linux harness。Linux 使用四个新的 WDIO 会话: 基础 (auth,navigation,system), 聊天 (chat,skills,journeys), 连接 (providers,provider-web,connectors)以及 设置 (settings,notifications)。Payments 和 webhooks 在其浏览器负责人迁移到 Playwright 后不再有原生流程,因此它们不在原生分片分配中。整合审查了 51 对具有相同基名的原生/Playwright 文件;只保留了 5 个窄范围拆分的混合案例,并退役了 1 对过时的 offline-banner pair。原生套件还保留了 24 个原有的仅原生文件,这些文件不在重复清单中,外加 tauri-commands.spec.ts,其浏览器启动检查已转移到 Playwright smoke 负责人,而其原生 IPC 检查仍保留。那 24 个仅原生文件并未评估是否需要桌面主机。可复用工作流也将相同的组定义应用到其 macOS 和 Windows 完整套件作业上,但这些作业目前已禁用。
因此,macOS 和 Windows 桌面 E2E 在任何分支上都没有计划覆盖。 .github/workflows/e2e.yml 是一个手动触发,其 run_macos 和 run_windows 输入默认也为 false。旧的基于 Chromium 的驱动依赖 CEF/CDP,在 Wry 下不可用;不要把那些作业描述为有效覆盖。
运行器所有权和混合宿主案例
每个 spec 文件只属于一个运行器。将浏览器渲染 UI、浏览器路由、表单、聊天渲染和设置持久化放在 app/test/playwright/specs/。保留 app/test/e2e/specs/ 用于需要真实桌面进程、真实 Tauri 命令、操作系统通知权限、原生深链接启动、窗口行为或 core 重启的检查。单独的 JSON-RPC 调用并不会使测试成为桌面测试。将共享的元素操作保留在 app/test/e2e/helpers/element-helpers.ts.
有五个文件故意同时存在于两个运行器目录中,因为两边分别证明了不同的契约:
smoke.spec.ts
运行中的 Wry 窗口、应用 chrome 和正常的嵌入式 core 启动
浏览器根/chrome、独立 core 启动 URL/token 和 RPC
login-flow.spec.ts
桌面窗口和深链接 token 处理,包括无效、过期或绕过情况
浏览器回调入口、token/profile 结果、浏览器绕过和 onboarding
auth-access-control.spec.ts
桌面重新认证和原生 auth-expiry 事件投递
账户/账单/注销/撤销 UI 和权威认证状态
notifications.spec.ts
操作系统权限状态和真实通知插件调用
渲染的通知标题/正文和 System Events/空 Alerts UI
settings-data-management.spec.ts
重置 IPC、用户数据擦除和嵌入式 core 重启
清除数据确认和取消 UI
可执行文件保护 pnpm e2e:ownership:check 会拒绝任何其他重复项、过时例外或缺失文件。在添加 spec 之前,先决定由哪个运行时拥有该行为,在两个 spec 目录中搜索等价流程(包括已重命名文件),并且只将它添加到所属套件中。如果宿主和浏览器案例覆盖的是不同的行为,请明确命名并文档化两者职责;绝不要为了多一点信心而保留第二份完整副本。
当前清单有 30 个原生 spec 文件和 111 个 Playwright spec 文件,只有上面的 5 个混合文件按基名共享。那 24 个原有仅原生文件在重复清单之外,且未评估它们是否需要桌面主机; tauri-commands.spec.ts 保留了上面描述的原生 IPC 检查。offline-banner E2E 已退役,因为在这个基线之前其唯一的 UI 消费者已经被移除;聚焦的 connectivity-selector 和 listener 单元测试保留了设备/后端区分,并且不声称有任何 E2E banner 覆盖。
故障排查
Linux:“WebView 未就绪”超时
这通常意味着 tauri-driver 从未到达其 /status 端点,或者应用在挂载 webview 之前崩溃了。使用 app/scripts/e2e-run-session.sh使用 tauri-driver 并在调用 WDIO 之前等待该端点,而不是手动驱动应用。
确保 DISPLAY 已设置且 Xvfb 正在运行:
另外还要确保 dbus 正在运行(webkit2gtk 需要它):
Linux: tauri-driver 或 WebKitWebDriver 未找到
安装 tauri-driver 使用 cargo install tauri-driver,并确保 WebKitWebDriver 位于 PATH (在 Debian 和 Ubuntu 中,它随 webkit2gtk-driver)或者将 WEBKIT_WEBDRIVER 指向其所在位置。 e2e-run-session.sh 默认为 /usr/bin/WebKitWebDriver.
macOS:深度链接无法在 tauri dev
深度链接需要一个 .app 打包。请使用 pnpm tauri build --debug --bundles app 代替。
Docker:首次运行时构建较慢
第一次 Docker 构建会编译 Rust 并安装 E2E 运行所需的依赖。后续运行会使用缓存层。Docker 卷会缓存 Cargo registry 和 git 源码。
规范:通知
混合通知用例有各自的负责人。Playwright 会验证可见的通知标题/正文以及 System Events/空 Alerts UI。WDIO 只检查原生权限状态值并调用操作系统通知插件。请通过 lane 调度器运行浏览器负责人,或使用以下命令运行原生负责人:
原生测试套件使用一个实时 tauri-driver 会话;它不负责普通的通知列表 RPC 或页面渲染断言。此前的连接横幅 E2E 已被移除,因为在基线之前,源历史已经删除了其唯一的 UI 消费者;专注的选择器和监听器单元测试仍然覆盖设备/后端连接性差异。这里不声明浏览器横幅覆盖。
代理可观察的产物流转
开始一个编辑器测试
聊天草稿按线程保留。在规范输入其初始提示之前,请调用 replaceChatComposerText(input, prompt) 来自 app/test/playwright/helpers/chat-composer.ts。它会选中并删除恢复的草稿,等待值为空,通过键盘事件输入,并检查精确提示。使用 clearChatComposer(input) 当某个用例需要一个空编辑器时使用。这些辅助函数同时支持 textarea 和 Lexical 界面。
执行草稿恢复或追加后续内容的用例应保留其草稿,并显式驱动该行为。该辅助程序的浏览器回归测试位于 app/test/playwright/specs/chat-composer-helper.spec.ts.
对于一个规范且可检查的运行,它会将截图、页面源转储和模拟请求日志保存到磁盘:
产物保存在 app/test/e2e/artifacts/<timestamp>-agent-review/ ,默认情况下;设置 E2E_ARTIFACT_DIR 以覆盖该路径。该脚本会将该目录传递给 Playwright 作为输出路径,测试结果和附件会保存于此。审查用例会通过 testInfo.attach附加检查点截图、页面 HTML 以及经过脱敏的模拟请求日志。Playwright 还会在失败时保留其配置的 trace、截图和视频产物。完整详情和辅助 API: agent-observability.md.
Rust 推理提供方端到端测试
这些测试(tests/inference_provider_e2e.rs)使用 wiremock 模拟 HTTP 上游,且不需要真实的 LLM API 调用。它们涵盖 OpenAI 兼容聊天、Anthropic 认证风格、按模型抑制 temperature、Ollama 本地提供方,以及 /v1 HTTP 端点认证层。
另请参见
测试策略:某个测试属于哪一层。
代理可观测性:审查运行写入的产物流转。
Tauri shell:Wry webview
tauri-driver所附加到的。开始设置:本地 E2E 构建所需的工具链和子模块。
最后更新于