Automation

The automation server exposes runtime state and accepts commands via a file-based protocol. Use it for integration testing, CI smoke tests, and inspecting running apps.

Enabling automation

Build with the automation flag:

zig build run-webview -Dautomation=true

In your runner, pass an automation.Server to 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,
});

The default directory is .zig-cache/zero-native-automation.

File protocol

When the runtime publishes a snapshot, it writes these files to the automation directory:

File	Description
`snapshot.txt`	Runtime state: app name, source kind, window metadata, `ready=true/false`
`accessibility.txt`	Accessibility tree summary
`windows.txt`	Window list: `window @w{id} "{title}" focused={bool}` per line
`screenshot.ppm`	Screenshot in PPM format (currently a 2x2 placeholder)
`command.txt`	Command input: written by the CLI, consumed by the runtime
`bridge-response.txt`	JSON response from the last bridge command

Commands

The runtime polls command.txt and processes these actions:

Action	Description
`reload`	Reload the WebView source
`wait`	Block until the snapshot shows `ready=true`
`bridge <json>`	Send a bridge command with origin `zero://inline`

After processing a command, the runtime writes done to command.txt.

CLI usage

The zero-native automate subcommand interacts with the automation directory:

# Wait for the app to be ready (polls snapshot.txt for ready=true)
zero-native automate wait

# List running automation-enabled apps
zero-native automate list

# Dump the current snapshot
zero-native automate snapshot

# Capture a screenshot
zero-native automate screenshot

# Reload the WebView
zero-native automate reload

# Send a bridge command and get the response
zero-native automate bridge '{"id":"1","command":"native.ping","payload":{"source":"automation"}}'

Testing with automation

The test-webview-smoke build step demonstrates a full automation test flow:

Build and start the app with -Dautomation=true
Run zero-native automate wait to block until the app is ready
Run zero-native automate snapshot to verify window metadata and source kind
Run zero-native automate bridge '...' to test the native bridge round-trip
Verify the response in bridge-response.txt

zig build test-webview-smoke -Dplatform=macos

Custom directory

Pass a custom path to automation.Server.init():

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

The CLI reads from the default .zig-cache/zero-native-automation unless you specify a directory via the automation subcommand.