自动化测试 (Automation)

自动化服务器（Automation server）会暴露运行时状态，并以基于文件系统的协议来接收并执行相关指令。它通常用于集成测试、持续集成（CI）冒烟测试以及对运行中的应用进行状态调试与分析。

启用自动化

构建时加上自动化相关参数：

zig build run-webview -Dautomation=true

在您的启动程序（runner）中，将 automation.Server 实例传入 RuntimeOptions：

const server = zero_native.automation.Server.init(io, ".zig-cache/zero-native-automation", "My App");
var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .automation = server,
});

默认生成的自动化工作目录为 .zig-cache/zero-native-automation。

文件级通信协议 (File protocol)

当运行时输出应用状态快照时，它会将以下文件写入到自动化的工作目录中：

文件名	描述
snapshot.txt	运行时状态：包含应用名、渲染源类型、窗口元数据以及 ready=true/false 状态。
accessibility.txt	辅助功能树（Accessibility tree）的概述。
windows.txt	窗口列表：每行对应一个 window @w{id} "{title}" focused={bool} 的窗口信息。
screenshot.ppm	PPM 格式的屏幕截图（目前仅为一个 2x2 的占位图像）。
command.txt	指令输入通道：由 CLI 写入，被运行时读取并消费。
bridge-response.txt	上一个桥接命令执行返回的 JSON 响应结果。

支持的指令 (Commands)

运行时会轮询 command.txt 文件的变化，并处理以下操作：

指令操作	描述
reload	重新加载 WebView 渲染源。
wait	阻塞等待，直到快照输出中显示 ready=true。
bridge <json>	以 zero://inline 作为源发送一个桥接命令。

在处理完一条指令后，运行时会向 command.txt 中写入 done。

命令行（CLI）使用方法

zero-native automate 子命令可以与自动化目录进行交互：

# 等待应用就绪（轮询校验 snapshot.txt 中的 ready=true 字段）
zero-native automate wait

# 列出当前启用了自动化测试的所有运行中应用
zero-native automate list

# 打印当前应用的状态快照
zero-native automate snapshot

# 捕获应用屏幕截图
zero-native automate screenshot

# 重新加载 WebView 页面
zero-native automate reload

# 发送桥接指令并获取返回响应
zero-native automate bridge '{"id":"1","command":"native.ping","payload":{"source":"automation"}}'

通过自动化进行测试

构建步骤中的 test-webview-smoke 展示了完整的自动化测试流程：

1. 使用 -Dautomation=true 编译并启动目标应用；
2. 运行 zero-native automate wait 阻塞进程，直至应用加载并处于就绪状态；
3. 运行 zero-native automate snapshot 以验证窗口的元数据以及源类型；
4. 运行 zero-native automate bridge '...' 来测试原生桥接通道的往返调用；
5. 校验 bridge-response.txt 中返回的 JSON 响应是否符合预期。

zig build test-webview-smoke -Dplatform=macos

自定义目录 (Custom directory)

您可以向 automation.Server.init() 中传入一个自定义的输出路径：

const server = zero_native.automation.Server.init(io, "/tmp/my-app-automation", "My App");

CLI 默认会去读取 .zig-cache/zero-native-automation 路径下的内容，除非您在执行 automate 子命令时通过参数显式指定了其他自定义目录。