Orca E2E 测试实战指南--mode e2e 构建、window.__store 调试通道与 Playwright 断言分层【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca本篇指南基于 Orca 仓库的 E2E 测试规范文档 tests/e2e/AGENTS.md 展开结合 global-setup、Playwright 配置 与渲染层 store 源码讲清三件实战问题为什么 E2E 构建必须带--mode e2e、window.__store调试通道的正确用法边界、以及何时该退回 store-slice 单元测试。读完后你能独立排障E2E 全量 30s 超时这类构建模式故障并为新测试选定正确的测试层级。一、跑 E2E 前必须用--mode e2e构建应用1.1 问题本质window.__store只在 e2e 构建中暴露Orca 的 E2E 规格通过window.__store直接读取 Zustand 状态。这个全局量仅在 preload bundle 以e2e模式构建时才会被赋值而该模式由传给electron-vite build的--mode e2e触发。源码中的暴露逻辑位于 store 入口// E2E tests (VITE_EXPOSE_STORE). The E2E suite reads store state directly testWindow.__store useAppStore也就是说普通的pnpm build或pnpm build:electron-vite产出的out/目录不包含store 暴露逻辑。如果此时用SKIP_BUILD1复用这份产物每一个 spec 都会卡在waitForFunction(() Boolean(window.__store))上直到 30s 超时。global-setup 中的构建步骤印证了这一点——构建命令显式携带--mode e2e并同时设置环境变量作为兼容兜底// Why: --mode e2e is the build-time signal that exposes window.__store; // the explicit env var keeps older local overrides working too. console.error([e2e] Building Electron app with electron-vite build --mode e2e...) execSync(npx electron-vite build --mode e2e, { env: { ...process.env, VITE_EXPOSE_STORE: true }, cwd: root, stdio: inherit, timeout: ELECTRON_E2E_BUILD_TIMEOUT_MS })1.2 两种运行路径与一条排障铁律原文档给出了两条运行路径均可直接复制使用默认路径pnpm run test:e2e—— 由globalSetup自动执行electron-vite build --mode e2e无需手动构建。快速迭代先手动执行一次pnpm exec electron-vite build --mode e2e之后用SKIP_BUILD1 pnpm run test:e2e …跳过重建。SKIP_BUILD的行为在 global-setup 中有明确判定仅当SKIP_BUILD已设置且out/main/index.js存在时才跳过构建因此该开关的前提仍然是产物由--mode e2e构建而来。由此得到一条排障铁律如果所有 E2E 测试都在window.__store这一行超时不要先怀疑测试框架坏了——out/构建几乎必然是陈旧的或根本不是用--mode e2e产出的。正确动作是重新用--mode e2e构建后再试而不是去改测试代码。1.3 globalSetup 的完整职责构建 幂等测试仓库从 global-setup.ts 的完整实现看globalSetup还承担了两项保证套件幂等性的工作理解它们有助于解释 E2E 的各种前置条件构建三类产物Electron 主程序out/main/index.js、bundled CLIout/cli/index.js以及在ORCA_E2E_WEB_CLIENT1时构建配对浏览器 web 客户端out/web/web-index.html同样注入VITE_EXPOSE_STOREtrueSSH 类场景ORCA_E2E_SSH_DOCKER1等还会额外构建 Relay 包并准备 Docker OpenSSH fixture 镜像。创建专属种子 git 仓库每次运行都在临时目录git init一个带 README、package.json、源码文件的新仓库并额外git worktree add出第二个 worktree供 worktree 切换类测试终端内容保留、浏览器 tab 保留使用仓库路径写入临时文件ORCA_E2E_TEST_REPO_PATH_FILE供 worker fixture 读取。使用realpathSync是因为 macOS 上os.tmpdir()的/var/...是符号链接需要与 store 中git rev-parse --show-toplevel规范化后的repo.path保持一致。这意味着测试套件不依赖你本地打开的任何仓库天然幂等。二、逻辑是纯函数时优先写 store-slice 单元测试2.1 为什么 E2E 里调store.getState()是付了单测的钱原文档指出一个在page.evaluate里调用store.getState().someAction(...)的 E2E spec本质上是以一次 Electron 启动的成本约 1.5s在跑单元测试却没有换来任何额外覆盖。添加这类测试前应先检查src/renderer/src/store/slices/*.test.ts——大多数 store 级行为tab 移动、分屏、排序、合并、no-op 守卫已经用createTestAppStore()在单元层覆盖。2.2 E2E 的适用边界清单只有当测试需要单元测试真正触达不到的能力时才值得写 E2E。原文档给出的边界清单如下真实的 dnd-kit / 指针事件、焦点、键盘快捷键或拖放 UI 反馈经由主进程的 IPC 往返repos、文件系统、PTY、Git持久化行为应用重启、userData 目录、会话再水化rehydration依赖 Electron 生命周期的多窗口或多 worktree 交互。判断标准很简单如果测试可以改为直接 import 该 slice 并驱动它、且不损失保真度就应该那样写。三、E2E 断言必须面向 DOM而不是 store3.1window.__store的正确角色搭状态不验结果window.__store适合用于setup——预置仓库、预填草稿、打桩水化时机——但 spec 最终expect()的对象必须是用户可观察的getByRole、toBeVisible、toHaveText、toContainText。一个既写 store 又读 store 的 spec断言的是 Zustand 的 setter 能工作而不是 Orca 能工作。3.2 一个真实事故store 层通过、真实用户崩溃原文档记录了一次具体事故说明这条规则的必要性create-worktree这个 modal key 在AddWorktreeDialog.tsx被删除#710后仍长期留在activeModal联合类型里。于是store.openModal(create-worktree)store.activeModal create-worktree的回环断言持续通过——对着一张渲染出空内容的 modal。正是这个恒真断言让 #1186StartFromField中的 React error #31得以流出store 层测试全绿而真实用户的 composer 实际在崩溃。由此得到三条可操作的规则用 store 到达某个状态用 DOM 证明状态是正确的如果某个渲染层回归会让 store 保持干净而 UI 坏掉那么 store-only 测试必然抓不到它——应把受影响的子树挂载起来断言用户实际看到的东西Headless 模式ORCA_E2E_HEADLESS1不豁免此规则——Playwright 通过 CDP 驱动的是真实 DOM与窗口是否可见无关。少数确实需要焦点或指针捕获的场景改用ORCA_E2E_HEADFUL1。3.3 headless / headful 的项目级落地playwright.config.ts 中headless 与 headful 是通过两个 project落地的而非简单环境变量切换projects: [ { name: electron-headless, testMatch: **/*.spec.ts, grepInvert: /headful/, metadata: { orcaHeadful: false } }, { name: electron-headful, testMatch: **/*.spec.ts, grep: /headful/, metadata: { orcaHeadful: true } } ]带headful标记的 spec 只会跑进electron-headful项目spec 代码则通过project.metadata.orcaHeadful读取该标记来决定是否以可见窗口启动。这与 AGENTS.md 中rare cases that need focus or pointer capture useORCA_E2E_HEADFUL1viaproject.metadata.orcaHeadful的描述完全对应。同配置里还有几条与排障直接相关的设置值得了解单测预算timeout: 120_000覆盖冷启动开销、CI 下workers: 1避免两个 Electron 进程在同一 VM 上争抢 Xvfb/git 导致假失败CI 靠分片扩缩、retries: 0且trace: retain-on-failure首失败的 trace 是 CI 上唯一可靠的调试产物。小结E2E 质量门禁的三条可执行检查项回到 tests/e2e/AGENTS.md 的核心脉络给新贡献者的三条检查项跑之前确认out/由--mode e2e构建pnpm run test:e2e会自动保证手动SKIP_BUILD1时须自行先跑pnpm exec electron-vite build --mode e2e。全量 30s 超时优先怀疑构建模式而不是测试框架。写之前判断逻辑是否纯——能落到src/renderer/src/store/slices/*.test.ts的不进 E2E只有 dnd/指针、IPC 往返、持久化、多窗口生命周期四类能力才配 E2E。断言时store 只用来搭状态expect()只面向getByRole等 DOM 断言headless 与 headful 在断言规则上没有豁免。这套约束的底层动机只有一个E2E 的稀缺价值在于覆盖渲染层与进程边界的真实行为任何把它退化成 store 自证的行为都会像create-worktree事故那样让 store 层的全绿掩盖 UI 层的真实崩溃。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考