跳转到内容
For the complete documentation index, see llms.txt. This page is also available as Markdown.

端到端测试

如何运行端到端测试套件:使用 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 smoke

app/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-refresh

  • cron-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-button

  • onboarding-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 功能。

  1. 正常启动 OpenHuman 并保持其运行。

  2. 触发 openhuman://auth?token=e2e-token&key=auth 通过操作系统打开器。

  3. 确认已在运行的窗口接收到回调,而不是启动第二个应用实例。

  4. 确认辅助进程干净退出。

这可以捕获在 Tauri 的深链接转发路径安装之前就启动,或以错误退出的第二个实例。

编写跨平台 spec

  1. 使用中的辅助函数 element-helpers.ts。切勿在 spec 中直接使用原始 XCUIElementType* 选择器。

  2. 使用 clickNativeButton(text) 而不是内联按钮点击代码。

  3. 使用 hasAppChrome() 而不是检查 XCUIElementTypeMenuBar.

  4. 使用 waitForWebView() 而不是检查 XCUIElementTypeWebView.

  5. 对于仅限 macOS 的测试,使用 process.platform 守卫或单独的 spec 文件。

  6. 使用 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.

有五个文件故意同时存在于两个运行器目录中,因为两边分别证明了不同的契约:

文件
原生 WDIO 断言
Playwright 断言

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 端点认证层。


另请参见

最后更新于