automation

name	automation
description	Automation and verification guide for running zero-native WebView shell apps. Use when the user asks to test an app, inspect runtime state, list windows, wait for readiness, reload a WebView, send bridge commands, debug why automation is not connected, create smoke tests, or verify a zero-native example in a GUI-capable session.

Automate zero-native apps

zero-native has a built-in automation system for inspecting running WebView shell apps. It works through file-based IPC in .zig-cache/zero-native-automation/ and is intended for smoke tests, CI checks with a GUI session, and quick runtime inspection.

Automation is not browser DOM automation. It reports runtime/window/source state and can ask the runtime to reload or dispatch bridge requests. For frontend DOM testing, use the frontend framework's tests or a browser automation tool against the dev server.

What automation can verify

• An automation-enabled app started and published ready=true.
• The runtime loaded the expected app name, source kind, and window metadata.
• The main window exists and is focused/open.
• The JavaScript-to-Zig bridge can round-trip a request through zero-native automate bridge.
• Builtin window/WebView commands work when exercised by a smoke test.
• Reload requests are accepted by the runtime.

What automation cannot verify

• Real screenshots. Current screenshot support is a placeholder/unsupported depending on backend.
• Arbitrary DOM queries and clicks.
• Visual layout correctness.
• Browser network assertions.

Prerequisites

Build/run an app with automation enabled. Generated examples usually expose -Dautomation=true:

zig build run -Dplatform=macos -Dautomation=true

Repository examples may have specialized steps:

zig build run-webview -Dplatform=macos -Dautomation=true
zig build test-webview-smoke -Dplatform=macos

The runner must pass an automation server into 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,
});

Apps built without -Dautomation=true usually ignore automation files.

Commands

zero-native automate wait
zero-native automate list
zero-native automate snapshot
zero-native automate reload
zero-native automate bridge '{"id":"smoke","command":"native.ping","payload":{"source":"automation"}}'

If using the repository-built CLI:

zig-out/bin/zero-native automate wait
zig-out/bin/zero-native automate snapshot

Standard workflow

1. Start the app with automation enabled.
2. Run zero-native automate wait to block until snapshot.txt contains ready=true.
3. Run zero-native automate snapshot to confirm app/window/source metadata.
4. Run zero-native automate list to inspect window summaries.
5. Run zero-native automate bridge '...' for bridge round-trip checks.
6. Use zero-native automate reload to request a WebView reload.

Bridge smoke test pattern

The request must be JSON with an ID, command, and payload:

zero-native automate bridge '{"id":"smoke","command":"native.ping","payload":{"source":"automation"}}'

Automation sends the request with origin zero://inline. The app's bridge policy must allow that origin or the call will reject with permission_denied. For packaged asset origins, app code often allows zero://app; for automation smoke tests, add zero://inline only when the test needs it.

Expected response shape depends on the handler. A typical native.ping handler returns:

{"id":"smoke","ok":true,"result":{"message":"pong","count":1}}

If the command fails, inspect the bridge error code:

• unknown_command: no handler registered or wrong command name.
• permission_denied: origin or permission policy blocked it.
• handler_failed: Zig handler returned an error or invalid JSON.
• payload_too_large: request exceeded bridge limits.

File protocol

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

Files:

• snapshot.txt: app name, readiness, source kind, source size, window metadata, accessibility summary.
• windows.txt: window list.
• command.txt: command input written by CLI and consumed by runtime.
• bridge-response.txt: last bridge response.
• screenshot.ppm: placeholder screenshot artifact when supported by the runtime layer.

The runtime polls command.txt. After processing a command, it writes done.

Debugging automation failures

If zero-native automate wait times out:

1. Confirm the app is still running.
2. Confirm it was built with -Dautomation=true.
3. Confirm the runner passes automation into Runtime.init.
4. Check .zig-cache/zero-native-automation/snapshot.txt.
5. Delete stale files in .zig-cache/zero-native-automation/ and restart the app.
6. Run with more tracing, for example zig build run -Dtrace=all.

If snapshot says no app connected:

• The automation directory may not exist yet.
• The app may be running from a different working directory.
• The app may be built without automation.
• The app may not have reached runtime startup.

If bridge automation fails:

• Check command name spelling.
• Check app handler registration.
• Check bridge policy origins for zero://inline.
• Check runtime permissions.
• Check that the handler returns valid JSON.

CI and smoke tests

Use automation for minimal integration confidence:

zig build test-webview-smoke -Dplatform=macos

A good smoke test:

1. Builds an example with -Dautomation=true and -Djs-bridge=true.
2. Starts the app in a GUI-capable session.
3. Waits for readiness.
4. Verifies snapshot metadata.
5. Sends native.ping.
6. Exercises builtin windows/WebViews if the app enables them.
7. Fails on timeout or unexpected bridge response.

Do not use automation for exhaustive UI testing. It is a runtime and bridge smoke layer.

Notes

• Automation is compile-time gated: apps built without -Dautomation=true ignore automation files.
• The current screenshot artifact is a placeholder PPM or unavailable depending on backend.
• WebView DOM interaction is intentionally out of scope for this file-based automation layer.
• Use zero-native skills get core --full for app architecture, bridge policy, packaging, and debugging context.