Testing

The three test tiers, the machine lock, and reading the incident bundle before reproducing a bug.

Test in the cheapest tier that can see the behaviour. Read the last incident before you try to reproduce a bug. Rules in short: donts.md.

Three tiers, one semantic tree

Every tier reads the same semantic tree (role, name, value, test id, bounds, enabled, focused, checked, selected), so a locator written for one tier reads the same in the others.

nd test runs tiers 1 and 2 in parallel, every test in its own process. Tier 3 is a test whose name starts with real_ or sits in a real module (tests/real.rs); those run one at a time.

Tier 1

use nd::test::{TestApp, click, text};

#[nd::test]
fn add_one_counts_each_click(cx: &mut TestApp) {
    let window = my_app::open(cx).id();
    click(cx, window, "add");
    assert!(text(cx, window).contains("1"), "{}", text(cx, window));
}

• #[nd::test] gives a fresh TestApp and runs the same test natively and in a browser under wasm-bindgen-test. Tests are synchronous; cx.run_until_idle() settles frames and queued events.
• nd::test::{tree, by_test_id, text, click} read and drive the tree by test id (an element's explicit id). cx.emit(node, event) delivers an event as the backend would.
• Time is the test clock: cx.advance_clock(1. / 60.) ticks every window one frame.
• cx.render_count(entity_id) proves a view did not re-render, which is how you test that a list update leaves clean rows alone.
• The same locators as tier 3 run in process: nd_test::TestHarness::new(TestApp::new()) (add nd-test as a dev-dependency).

Tier 2: the appearance audit

tests/appearance.rs opens each window in light and dark on every backend kind the target links (plus two matugen palettes on GPUI), reads back every fill and text run, and fails on a colour that is not a theme token (or a state derived from one) and on text under WCAG contrast (4.5:1, or 3:1 for large text). Every window you add gets a .window(..) line:

fn main() {
    nd::audit::Audit::new("my-app", my_app::app)
        .window("main", |cx| my_app::open(cx).id())
        .window("settings", |cx| my_app::open_settings(cx).id())
        .run()
}

Colours your theme.rs names on purpose go through .allow(theme::colors()). Golden images re-record with ND_BLESS=1; a drifted golden leaves the diff image next to the test.

Tier 3

use nd_test::{LaunchOptions, Role, expect, launch_app};

#[test]
fn real_add_one_updates_the_count() {
    let app = launch_app(LaunchOptions::new(env!("CARGO_BIN_EXE_my-app"))).expect("launch");
    app.get_by_test_id("add").click().unwrap();
    expect(&app.get_by_role(Role::Text).name("1").exact()).to_be_visible().unwrap();
}

Locators: get_by_test_id, get_by_role(..).name(..), get_by_text, get_by_label, locator("role=button[name=\"Save\"] >> nth=1"). Actions wait for the element to be actionable; expect(..) polls until the session timeout (5 s). Each launch gets its own data directory (ND_APP_DATA_DIR) and socket, so two runs never share settings or logs.

The machine lock

Real input, window activation and screen capture use the one cursor and the one focus the machine has. Tier 3 runs that need them take a machine-wide lock (flock on real-input.lock under ~/Library/Caches/nd/ on macOS, ~/.cache/nd/ on Linux, %LOCALAPPDATA%\nd\ on Windows). A second agent's run, in this worktree or any other, queues behind it and prints the holder's worktree and purpose instead of stealing focus mid-test.

• launch_app holds it by default on macOS (LaunchOptions::machine_lock(false) for an app that only gets events posted into its own queue).
• A test that moves the real cursor holds nd_test::real_input("why") for as long as it does.
• ndshell lock status shows who holds it; ndshell lock -- <command> runs anything under it.
• A queued run is waiting, not hung. Do not kill the holder, and never delete the lock file.

Before reproducing a bug: read the incident

Every nd app runs a flight recorder: the last 5000 log events, the last 200 inputs, the semantic tree, frame records and open overlays. A panic, native crash, hang or nd::report_issue("what happened") writes all of it to an incident bundle under the app's data directory (diagnostics/<timestamp>-<kind>/).

nd diagnose --last        # newest bundle: what crashed, the app's frames, last inputs, the tree
nd diagnose --list        # every bundle, newest first
nd diagnose <id> --json   # one bundle, machine-readable

Start there. The bundle already says which window was focused, what was on screen and what the user pressed, so most bugs need no reproduction run at all. When the app itself knows something went wrong, call nd::report_issue(..) (it returns the bundle path) rather than logging and hoping someone runs it again. Bundles clean themselves up: newest 20, none older than 14 days, 200 MB in total.

Scripts around tests

• Delete only what your code made, by a path it built and checked. No rm -rf "$DIR/" on a variable that can be empty, no remove_dir_all outside a root you own.
• Stop processes by the pid you started. Never pkill -f <pattern>; other agents' apps match.
• No VMs and no sleeps waiting for a window: expect(..) and wait_for_stderr poll.