Automation

The automation server exposes runtime state and accepts commands via a file-based protocol. A running app publishes an accessibility snapshot — every widget with its id, role, name, bounds, and state — and accepts scripted clicks, keys, drags, and assertions against it. Use it for integration testing, CI smoke tests, inspecting running apps, and letting AI agents verify their own UI work.

Enabling automation

Build with the automation flag (native verbs forward -D flags to the underlying zig build):

native build -Dautomation=true

In your runner, pass an automation.Server to RuntimeOptions:

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

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

File protocol

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

Commands

The runtime watches the command queue and processes these actions:

Commands queue as command-<n>.txt entries: each native automate <command> claims the next sequence number exclusively (rapid back-to-back invocations can never overwrite each other), the app consumes one entry per presented frame in strict arrival order, and deleting the entry is the consumption ack. The queue is bounded to a handful of entries — a writer finding it full retries until the app drains a slot and fails loudly (non-zero exit) if it never does. native automate <command> prints delivered <action> -> <dir> only after the app consumed its entry, so a dead or frozen app is always a loud failure, never a silently dropped command.

Widget verbs and screenshot address a gpu_surface view by its label across ALL open windows — snapshots enumerate every window's views and widgets, so a model-declared secondary window's canvas (a settings window) is drivable and capturable exactly like the main one, with no window argument.

CLI usage

The native automate subcommand interacts with the automation directory:

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

# Assert on the snapshot: each argument is a regex that must match
# (polls up to --timeout-ms, default 30000; --absent inverts)
native automate assert 'gpu_nonblank=true' 'role=button name="Reset"'
native automate assert --absent 'error event='

# List running automation-enabled apps
native automate list

# Dump the current snapshot
native automate snapshot

# Render a gpu_surface view to screenshot-main-canvas.png
native automate screenshot main-canvas

# Reload the WebView
native automate reload

# Resize the main window surface
native automate resize 900 640

# Dispatch command-source events
native automate menu-command app.refresh
native automate native-command app.refresh refresh-button
native automate shortcut app.refresh

# Drive retained canvas widgets
native automate widget-action canvas 2 press
native automate widget-click canvas 3
native automate widget-hold canvas 3            # press-and-hold (on_hold)
native automate widget-context-press canvas 3   # right-click (presents the menu)
native automate widget-context-menu canvas 3 1  # pick declared menu item 1

# Drive focus between native controls and WebViews
native automate focus refresh-button
native automate focus-next
native automate focus-previous

# Toggle per-stage frame timing; the snapshot then carries a
# frame_profile line (rolling p50/p90/max us per pipeline stage)
native automate profile on
native automate snapshot | grep -o 'frame_profile.*'
native automate profile off

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

Testing with automation

The WebView and native-shell smoke build steps demonstrate full automation test flows:

1. Build and start the app with -Dautomation=true
2. Run native automate wait to block until the app is ready
3. Run native automate snapshot to verify window, source, and native/WebView metadata
4. Run native automate resize ..., native automate bridge '...', focus traversal, or command-source actions such as native automate native-command ...
5. Verify bridge responses, relayout bounds, focus state, and updated snapshots

zig build test-webview-smoke -Dplatform=macos

Write-back

Because views are data, automation can go the other way too: select a widget in the running app, jump to the markup that authored it, and write an edit back into the source file — the app's own hot-reload watch picks the change up and repaints.

The read half is provenance. Every markup-built widget's structural id maps back to its authored source, captured at view build time: the file, the node's byte span and line:column, the template instantiation chain (a widget inside a template reports both its definition site and every <use> that put it there), and the iteration keys that say which <for> row it is. Widgets built with the Zig builder report authored=zig honestly — write-back edits markup files only.

# Where does this widget come from? (id from the snapshot, or hit-test a point)
native automate provenance kanban-canvas 6624116744891006388
native automate provenance kanban-canvas at 760 30

The write half is edit: typed, minimal-diff operations on the file the widget came from. An operation changes only bytes inside the target node's span — whitespace, comments, attribute order, and every other node survive byte for byte, proven by reparsing and diffing the parse trees before anything is written.

native automate edit kanban-canvas 6624116744891006388 set-text "Add task"
native automate edit kanban-canvas 6624116744891006388 set-attr variant secondary
native automate edit kanban-canvas 6624116744891006388 remove-attr variant

Edits refuse rather than guess: a widget authored in Zig, a file that changed on disk since the app loaded it (the provenance response carries the loaded bytes' hash, so concurrent edits are never clobbered), or an edit that would fail markup validation all stop with a teaching error and leave the file untouched. A successful edit needs no reload command — the markup watch (MarkupOptions.watch_path, a dev/Debug feature) reloads within its poll interval, so native automate assert on the snapshot is the way to await the repaint.

zig build test-writeback-smoke (macOS) drives the whole loop against the kanban example: query provenance, flip the button label through the verb, assert the repaint, verify the byte-exact diff, and flip it back.

Custom directory

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

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

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