run-gui-journeys

用途

run-gui-journeys 用于在一次性 Tart 虚拟机中运行或诊断 macOS GUI 流程，避免影响宿主机屏幕。它属于 steerlabs/opensteer 仓库，相关约束记录在 scripts/test-vm/README.md 中，涉及所有权、存储与 golden 规则。

前提条件

使用干净且已提交的代码检出。
Apple silicon macOS 环境，安装 Tart。
使用仓库锁定的 Node/pnpm 以及 Go。
命令默认在客户机的 apps/desktop 目录下执行。

主要能力与使用方式

通过 pnpm test:vm 在虚拟机中执行指定脚本。示例命令包括：

pnpm test:vm -- --mobile bash scripts/test-macos-journeys.sh
pnpm test:vm -- --mobile bash scripts/test-macos-journeys.sh saved-password
pnpm test:vm -- --mobile --revision <commit> bash scripts/test-macos-journeys.sh windows

可在一次调用中选择相关的原生流程。需要使用 shell 语法时，用 bash -c '...' 包裹。对于输入测试，可在客户机内设置重复次数，例如：

pnpm test:vm -- --mobile env OPENSTEER_CHROME_R0_REPEAT=5 bash scripts/test-macos-journeys.sh

宿主机上的 PersonKeyOrderTests 作为确定性防护保留，不应在宿主机运行 GUI 检查。

原生 smoke 资源通过 OPENSTEER_VM_NATIVE_RESOURCES 或 ~/.cache/opensteer/vm/native-resources 提供。修改原生种子输入后，仅在没有运行占用时删除 ~/.cache/opensteer/vm/<sha> 下受影响的 SHA 载荷缓存；重试会校验缓存载荷的校验和。

运行后检查

需检查打印的 ~/.local/state/opensteer/vm-runs/<run-id> 记录、阶段日志与客户机产物，确认所选用例通过且克隆清理完成；仅导出成功不足以说明问题。发生不可捕获的崩溃后，检查 job.json，只停止或删除其记录的 Tart 克隆，绝不删除活动锁文件。可用 pnpm exec tsx scripts/storage-retention.ts --dry-run 预览保留策略。

无凭据持久化客户机流程

仅适用于无凭据的持久化客户机。在 apps/desktop 下使用新的运行 ID（格式 yyyymmddThhmmssZ-xxxxxxxx，后缀为小写十六进制）、完整 HEAD SHA 和显式输出目录。每条命令单独运行，并始终执行 postflight：

bash scripts/test-macos-journeys.sh --preflight --run-id "$id" --out "$out"
bash scripts/test-macos-journeys.sh --run-id "$id" --sha "$sha" --out "$out" windows
bash scripts/test-macos-journeys.sh --postflight --run-id "$id" --out "$out"

preflight/postflight 返回非零时视为未认证状态，应隔离或重置客户机，而不是扩大清理范围。GUI golden 引导使用 pnpm test:vm:golden；失败后检查保留的 provisioning 日志。不要替换已有 golden 来强制重试。移动端 golden 设置归移动端所有者负责，需使用其授权输入与 provisioning 来源。

传输与生命周期变更

对于传输/生命周期变更，运行以下无需凭据且不涉及虚拟机的契约测试：

pnpm exec tsx scripts/test-vm/contract-journey.ts
pnpm exec tsx scripts/test-vm/guest-contract-journey.ts

适用场景与限制

适用于在隔离虚拟机中执行和排查 macOS GUI 旅程、验证相关原生流程及传输/生命周期契约。限制包括：依赖 Apple silicon macOS 与 Tart；不在宿主机执行 GUI 检查；持久化流程仅限无凭据客户机；golden 管理与移动端 golden 有独立责任方。其他细节暂未提供。