Testing and debugging

Contract and unit tests

pnpm test
pnpm build
pnpm typecheck

The JavaScript test suite covers reconciler mutation semantics, prop validation, bridge startup and failure behavior, sequence acknowledgements, menu and presentation data, and selection behavior.

Real-window suites

pnpm verify
pnpm verify:kitchen
pnpm verify:embedded
pnpm verify:package

These commands require a desktop window session and target the host for the current operating system. The embedded suite proves JavaScriptCore on macOS and V8 on Windows. The package suite first runs pnpm package:demo, launches the resulting native artifact from an unrelated working directory, validates its ready handshake and tree, then requests a normal close and requires a clean exit.

The base Node-mode and embedded suites have passed locally against a real Windows WinUI 3 window. The Windows CI job compiles the host, builds the portable EXE, and inspects its single-file contents without running a GUI.

The package configuration and generated manifest also have platform-neutral unit coverage through pnpm test. Those tests validate path containment, identity fields, stable manifest content, compatibility gates, SHA-256 shape, and macOS native metadata.

Debug messages

NatuiApp exposes four debug helpers:

const app = await run(<App />);

const tree = await app.dump();
await app.screenshot('/absolute/path/result.png');
app.emit(nodeId, 'press');
app.edit(nodeId, 'new value');

• dump returns the host's actual native node tree.
• screenshot asks the host to render its window to a PNG.
• emit synthesizes an event without optimistic local state.
• edit performs a real optimistic edit and exercises sequence acknowledgements.

Dump and screenshot requests time out rather than hanging forever. Screenshot failures return an error response and do not leave a successful-looking path.

Interpret evidence precisely

A native tree dump proves materialization and props. An event assertion proves bridge behavior. A host-rendered PNG proves visible window content. None of these alone proves every popup layer, focus transition, or accessibility interaction.