Editor test automation
Doppio is tested by driving the real widget tree off-screen: plain JSON scripts, human-like input, assertions, screenshots, baselines and GIF/MP4 recordings. There is no separate Python harness.
Note. Older revisions of this page described a Python
editor_test_automation.py process bridge. That harness is gone. The
supported path is doppio-headless and the committed UI flows.
The three layers#
| Layer | Location | Runs |
|---|---|---|
| Flow | doppio/tests/ui-flows/*.json | Every cargo test through every_shipped_flow_passes and through scripts/check-rust-ui.sh. |
| Driver | doppio/crates/ui/src/windows/main/headless/ | Actions, targets, state snapshots, screenshots and recording. |
| CLI | scripts/doppio-headless.sh | Any shell, CI job or agent; no window opens. |
Run the flows#
./scripts/doppio-headless.sh run doppio/tests/ui-flows --format text
Each flow gets its own artifact folder. A failing step prints the action, the target,
the messages it produced and a hint. Exit codes: 0 pass, 1 step/assertion failure,
2 usage or invalid JSON.
Write a flow#
{
"name": "Open the Scene menu and add an entity",
"description": "Guards keyboard and menu routing for the add action.",
"fixture": "entities",
"size": [1280, 720],
"steps": [
{ "action": "click", "target": "id:editor.menu.scene" },
{ "action": "expect", "state": { "/menu": "Scene" }, "exists": "text:Add Entity" },
{ "action": "click", "target": "id:editor.add_entity" },
{ "action": "expect", "count": { "prefix": "hierarchy.list.entity_row.", "at_least": 3 } },
{ "action": "screenshot", "name": "after-add", "annotate": true }
]
}
Guidelines:
- Start from a fixture (
entities,empty,material,texture,scene3d,nature,water,terrain). - Use catalogue ids (
id:...), not points, unless the point is the behaviour under test. - Assert after each meaningful action; put a
labelon assertions so failures read well. - Keep screenshots as artifacts; use
baselineonly when the visuals are the point. - Name the bug the flow guards in
description.
Inspect the UI#
./scripts/doppio-headless.sh widgets --size 1440x800
./scripts/doppio-headless.sh screenshot --annotate --name workspace --out /tmp/shots
widgets lists ids, kinds and bounds. screenshot --annotate numbers every
catalogued widget and appends the legend n. id — description. The same catalogue
drives the UI reference.
Capture documentation images#
Committed capture flows live in doppio/docs/flows/capture-*.json. Their shell
wrappers strip the numeric prefix so image names are stable:
./scripts/capture-material-docs.sh
./scripts/capture-nature-docs.sh
./scripts/capture-terrain-docs.sh
./scripts/capture-texture-docs.sh
./scripts/capture-water-docs.sh
./scripts/capture-gizmo-docs.sh
./scripts/capture-editor-tour.sh # short MP4/GIF tour
A capture flow is a normal flow plus screenshot steps with target, padding and
scale. See doppio/docs/flows/capture-gizmo-docs.json for the scene3d pattern.
Record GIFs and videos#
record_start / record_stop capture the window or one widget and encode with
ffmpeg:
{ "steps": [
{ "action": "record_start", "name": "dock", "format": "mp4", "fps": 30, "target": "id:editor.pane.viewport" },
{ "action": "drag", "from": "id:editor.pane.tab.console", "to": "point:900,300" },
{ "action": "wait", "ms": 1200, "real_time": true },
{ "action": "record_stop" }
] }
format accepts gif, mp4 and webm; width, scale, fps and keep_frames
control the output. A recording left open when the script ends is finished
automatically.
Regression rules#
- A user-visible fix or feature adds a flow under
doppio/tests/ui-flows/. - The flow must pass in
cargo testand inscripts/check-rust-ui.sh. - New widgets get a
UiIdand aCATALOGentry; otherwise they cannot be targeted, annotated or documented. - Visual changes regenerate the affected capture flow images; do not edit PNGs by hand.
Related pages#
- Headless testing reference — every action, target form, state key and screenshot option.
- UI reference — generated ids and captions.
- Building — test binaries and feature flags.