makepad/libs/makepad_test/GUIDE.md

makepad_test Guide

This guide covers how to write, run, and debug UI tests with makepad_test.

Authoring Model

Tests live beside the package they exercise, usually under tests/.

examples/text_input/
├── Cargo.toml
├── src/main.rs
└── tests/ui.rs

#[makepad_test] is current-package oriented by default:

• env!("CARGO_MANIFEST_DIR") provides the package directory
• env!("CARGO_PKG_NAME") provides the package to run

That keeps the normal Rust workflow intact: add a dev-dependency, write tests/*.rs, and run cargo test --release -p <package>.

Macro Behavior

#[makepad_test] expands to a normal #[test] wrapper that:

1. runs cargo build --release -p <package> from the package directory
2. selects the standalone executable from Cargo's compiler-artifact messages
3. launches that executable with --remote, hidden unless visible mode is requested
4. reads the owned PID and endpoint and waits for the app's first window
5. passes a TestApp into your test body
6. captures failure artifacts on returned errors or panics
7. requests /gq, falls back to /quit if needed, and confirms the owned child exits

Cargo's owning-workspace target is reused, including explicit CARGO_TARGET_DIR overrides. No build target is forced beneath each package. Tests keep their small artifact directories beneath the package directory.

Supported signatures:

#[makepad_test]
fn smoke(app: TestApp) {
    // ...
}

#[makepad_test]
fn smoke(app: TestApp) -> Result<(), TestError> {
    // ...
    Ok(())
}

Unsupported:

• async tests
• methods with self
• generic test functions
• macro arguments

Runtime Defaults

The runtime is synchronous and serial-first:

• action timeout: 10s
• poll interval: 50ms
• artifacts: <manifest_dir>/target/makepad_test/<package>/<test>/

The runner serializes app sessions within each test executable. Use --test-threads=1 for predictable suite order. MAKEPAD_TEST_PARALLEL=1 opts out of the runner lock when a suite is designed for concurrent owned instances.

Visible Mode and Configuration

The default is a hidden native window (MAKEPAD_HIDE_WINDOWS=1). To watch a standalone test window without focusing it:

MAKEPAD_TEST_VISIBLE=1 cargo test --release -p makepad-example-text-input --test ui -- --test-threads=1

Visible mode uses the same owned-process transport and never connects to an existing app or Studio session. The harness removes MAKEPAD_FOCUS from the child's environment.

Pacing variables:

• MAKEPAD_TEST_STARTUP_DELAY_MS=1000 waits after startup before the test starts
• MAKEPAD_TEST_ACTION_DELAY_MS=750 waits after each interaction
• MAKEPAD_TEST_KEEP_OPEN_MS=3000 pauses briefly before shutdown

For explicit configuration, construct TestConfig::new or TestConfig::current_package, adjust it, and pass it to run_with_config. bin_name selects a target in a package with several binaries; app_args adds arguments after --remote; visible controls visibility. env supplies app environment variables. Its CARGO_TARGET_DIR, when present, also applies to the build. Otherwise Cargo's inherited environment and configuration apply.

The former mount_name and listen_address fields and MAKEPAD_TEST_STUDIO/MAKEPAD_TEST_STUDIO_MOUNT settings no longer apply. There is no hub or mount to configure.

Selectors

Selectors are snapshot-based. They match structured widget state instead of only relying on geometry query strings.

Constructors:

• Selector::all()
• Selector::id("widget_id")
• Selector::widget_type("TextInput")
• Selector::raw("text:hello")

Builder filters:

• .text_exact("...")
• .text_contains("...")
• .nth(index)
• .window("panel_window")
• .window_index(1)
• .any_window()

Selectors default to the primary window. That keeps single-window tests terse while still allowing explicit multi-window targeting.

Locators

Locator methods require exactly one visible match for interaction. That strictness is intentional: it keeps tests from silently clicking the wrong widget.

Common actions:

app.locator(Selector::id("panel_input"))
    .wait_visible()
    .fill("hello")
    .wait_value("hello")
    .press_key(KeyCode::ReturnKey);

Available interaction helpers:

• click
• type_text
• fill
• clear
• press_key
• press_key_with_modifiers
• scroll
• drag_by

Available waits and assertions:

• wait_visible
• wait_hidden
• wait_count
• wait_text / assert_text
• wait_value / assert_value
• wait_checked / assert_checked
• wait_enabled / assert_enabled

Inspection helpers:

• snapshot()
• count()
• widget_snapshot()
• widget_dump()
• screenshot()
• wait_for_log_contains(...)

Lower-level escape hatch:

app.forward(vec![/* pointer, scroll, key, or text StudioToApp events */]);

forward translates supported input events to HTTP input routes. Other legacy protocol variants return an explicit error. Native timestamps are assigned at injection; key repeat and IME metadata are not forwarded. It does not provide live reload, window resizing, swapchains, clipboard forwarding, or hub control. Prefer the regular TestApp methods for snapshots, grabs, and logs.

Structured Widget State

Each snapshot record exposes:

• widget id
• widget type
• bounds
• window id and window index
• visible/enabled state
• widget-specific state when available:
  • text
  • value
  • checked
  • selected

Window names, enabled flags, and selections come from the actual widget snapshot. Missing required fields fail decoding instead of fabricating state. Optional state is absent when the widget does not expose it; empty labels may omit text, while an empty input value remains an empty string.

Interactions require visible geometry. State reads prefer visible matches and can fall back to a uniquely matched clipped widget, such as a label below a scrolling page.

Failure Artifacts

Failed tests write to:

<manifest_dir>/target/makepad_test/<package>/<test>/

Builds retain stderr; launched sessions also retain app stdout/stderr and a shutdown.txt record with the owned PID and shutdown result. Test-body failures additionally capture:

• failure.txt
• logs.txt
• widget-snapshot.json
• widget-tree.txt or widget-tree-error.txt
• failure-screenshot.png or failure-screenshot-error.txt

If a capture step fails, the runtime writes a *-error.txt file instead of silently dropping the artifact.

Running Tests

cargo test --release -p makepad-test
cargo test --release -p makepad-example-text-input --test ui -- --test-threads=1

Standalone Transport and Ownership

The runtime uses the app's documented HTTP remote surface: /s, /snap, /d, /g, /log, and input routes. Input requests wait for a resulting frame. Rectangles are window-local layout points; do not apply DPI conversion to clicks.

Screenshots are captured from the app's own drawable. Setting TestConfig::env["MAKEPAD_GPUSIM_DPI"] to a positive number scales screenshots to that pixel density for existing suites; it does not select a software renderer or change the native window's DPI.

Cleanup first uses /gq to save a final frame and quit. If capture is unavailable or the app remains alive, it sends /quit. A dropped response is not treated as proof that the process failed to exit. The runner waits for its owned Child and kills only that child after graceful shutdown times out. This cleanup also runs after test panics. It never stops, replaces, or drives user-owned instances.

Troubleshooting

If a test times out or fails to resolve a widget:

1. inspect target/makepad_test/.../logs.txt
2. inspect widget-snapshot.json for text/value/checked/selected state
3. inspect widget-tree.txt for the raw compact tree
4. verify the selector is scoped tightly enough

For startup failures, inspect build-stderr.txt, app-stdout.txt, and app-stderr.txt. shutdown.txt records whether the child exited normally or required the exact-PID fallback. For live diagnostics inside a test, app.pid(), app.remote_endpoint(), and app.grab_dir() identify only that owned instance.

A closed by user response is preserved as an error; the runner does not relaunch a dismissed app. Grabs have a longer request timeout because the backend must finish readback and PNG encoding.

Current Limitations

• the macro targets its current package; explicit configuration can select another
• synchronous API only
• no visual diffing or trace viewer yet
• some complex widgets still need more structured state over time

The native runtime and lifecycle fixtures are currently validated on macOS. Other platform backends may differ in capture support.